# Ledger Archive

## Archive Ledger Lines

Archives all ledger lines before a date cutoff across all accounts.

```
POST /ledger/archive
```

### Request

```json
{
  "before": "2026-07-01"
}
```

| Field    | Type   | Required | Description                                              |
| -------- | ------ | -------- | -------------------------------------------------------- |
| `before` | String | Yes      | Date cutoff (`YYYY-MM-DD`) — must be before today's date |

### Response — `200 OK`

```json
{
  "before": "2026-07-01",
  "accounts_affected": 1847,
  "records_created": 312,
  "records_updated": 48,
  "lines_archived": 284930,
  "lines_remaining": 41200
}
```

| Field               | Description                                                |
| ------------------- | ---------------------------------------------------------- |
| `accounts_affected` | Number of accounts that had lines archived                 |
| `records_created`   | New archive records created (each holds up to 1,000 lines) |
| `records_updated`   | Existing records that were appended to                     |
| `lines_archived`    | Total ledger lines moved to the archive                    |
| `lines_remaining`   | Ledger lines still in the live table                       |

### Errors

| HTTP | Code                  | Cause                                                  |
| ---- | --------------------- | ------------------------------------------------------ |
| 400  | `INVALID_FIELD`       | `before` is today, in the future, or malformed         |
| 409  | `INTEGRITY_VIOLATION` | Integrity pre-check found violations — archive blocked |

### Behavior

1. **Integrity pre-check** — validates all entities (accounts, journal entries, ledger, existing archives) before proceeding. Rejects if any violation is found.
2. **Version validation** — checks that ledger line versions are sequential with no gaps before archiving.
3. **Record packing** — fills existing records to 1,000 lines before creating new ones.
4. **Per-account transactions** — each account is processed independently. If the operation fails midway, already-archived accounts are safe.
5. **Idempotent** — resubmitting the same request is safe. Accounts with no qualifying lines are skipped.

### Example

```bash
curl -X POST http://<host>:8080/ledger/archive \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: ak_..." \
  -H "X-Api-Secret: sk_..." \
  -d '{"before": "2026-07-01"}'
```

***

## Read Archived Ledger

Returns one archive record per call for a specific account.

```
GET /account/:id/ledger/archive
```

### Query Parameters

| Parameter | Type    | Required | Description                                                 |
| --------- | ------- | -------- | ----------------------------------------------------------- |
| `from`    | String  | No       | Start date (`YYYY-MM-DD`), inclusive                        |
| `to`      | String  | No       | End date (`YYYY-MM-DD`), inclusive                          |
| `cursor`  | Integer | Yes      | `version_to` from previous response (use `0` on first call) |

### Response — `200 OK`

```json
{
  "account_id": "019702a0-...",
  "version_from": 1,
  "version_to": 1000,
  "created_at_from": "2025-12-28T00:00:00Z",
  "created_at_to": "2026-01-05T23:59:00Z",
  "balance_before": 0,
  "balance_after": 152300,
  "line_count": 1000,
  "lines": [
    {
      "operation": "CREDIT",
      "transaction_id": "...",
      "journal_entry_id": "...",
      "journal_entry_type": "PIX_IN",
      "journal_entry_sequence": 1,
      "asset": "BRL",
      "amount": 5000,
      "account_post_balance": 5000,
      "account_version": 1,
      "account_balance_policy": "NONE",
      "idempotency_key": "deposit-001",
      "created_at": "2025-12-28T10:30:00.123Z"
    }
  ],
  "next_cursor": 1000,
  "has_more": true
}
```

### Pagination

Use `next_cursor` as the `cursor` parameter for the next call:

```bash
# First call
curl "http://<host>:8080/account/<id>/ledger/archive?from=2025-01-01&to=2025-12-31&cursor=0"

# Next call
curl "http://<host>:8080/account/<id>/ledger/archive?from=2025-01-01&to=2025-12-31&cursor=1000"
```

Continue until `has_more` is `false`.

### Response Fields

| Field             | Description                                       |
| ----------------- | ------------------------------------------------- |
| `version_from`    | First `account_version` in this record            |
| `version_to`      | Last `account_version` in this record             |
| `created_at_from` | Earliest timestamp among lines in this record     |
| `created_at_to`   | Latest timestamp among lines in this record       |
| `balance_before`  | Balance just before the first line in this record |
| `balance_after`   | Balance after the last line in this record        |
| `line_count`      | Number of lines in this record (max 1,000)        |
| `lines`           | Array of ledger lines                             |
| `next_cursor`     | Value to use as `cursor` on the next call         |
| `has_more`        | Whether more records exist after this one         |

{% hint style="warning" %}
Records at date boundaries may contain lines outside the requested date range. Apply local filtering on the client side if you need exact date precision.
{% endhint %}

### Example

```bash
curl "http://<host>:8080/account/019702a0-.../ledger/archive?from=2025-01-01&to=2025-12-31&cursor=0" \
  -H "X-Api-Key: ak_..." \
  -H "X-Api-Secret: sk_..."
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://entrytarget.gitbook.io/docs/api-reference/ledger-archive.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.