---
title: "Append a ledger record"
description: "Requires a workspace-bound API key with ledger:write and an owner, admin, or member role. Appends one designator, observation, or claim. A designator with the same kind, namespace, and normalized value is reused (200, created false). Every claim cites at least one observation. The first line of a claim key supersedes nothing. Every later line, including a retraction, must supersede the current head, or the request fails with 409. Verification must be one the cited evidence supports: cross-linked and corroborated need retrievals of two different pages. Analytic means the only support is an analyst note. Other rule failures return 400 with the rule codes in detail. Send an Idempotency-Key header to make retries safe."
canonical: https://y2.dev/docs/api/reference/ontology-ledger/appendLedgerRecordV2/
---

Endpoint Reference[Ontology Ledger](https://y2.dev/docs/api/reference/ontology-ledger)

# Append a ledger record

Requires a workspace-bound API key with ledger:write and an owner, admin, or member role. Appends one designator, observation, or claim. A designator with the same kind, namespace, and normalized value is reused (200, created false). Every claim cites at least one observation. The first line of a claim key supersedes nothing. Every later line, including a retraction, must supersede the current head, or the request fails with 409. Verification must be one the cited evidence supports: cross-linked and corroborated need retrievals of two different pages. Analytic means the only support is an analyst note. Other rule failures return 400 with the rule codes in detail. Send an Idempotency-Key header to make retries safe.

`POST https://api.y2.dev/api/v2/ledger/records`

- Operation ID: `appendLedgerRecordV2`
- Required scopes: `ledger:write`
- Contract: https://y2.dev/openapi.json

## Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `Idempotency-Key` | header | string | No | Client-generated retry key retained for 24 hours. Repeating the same key and canonical JSON body returns the original resource. Changing the body returns `409 IDEMPOTENCY_CONFLICT`. |

## Request body

`application/json`: `LedgerRecordAppendRequest` (required)


## Responses

| Status | Description | Body |
| --- | --- | --- |
| 200 | Designator reused, or an idempotent replay. | `LedgerRecordAppendResponse` |
| 201 | Record appended. | `LedgerRecordAppendResponse` |
| 400 | Invalid request parameters |  |
| 401 | Missing or invalid API key |  |
| 403 | Insufficient permissions or access denied |  |
| 409 | Resource conflict (e.g., webhook in use) |  |
| 429 | Rate limit exceeded (per-key or per-account aggregate) |  |
| 500 | Internal server error |  |

### 200 response fields

| Field | Type | Description |
| --- | --- | --- |
| `data` | object |  |
| `data.id` | string |  |
| `data.type` | string |  |
| `data.kind` | `subject`, `designator`, `observation`, `assertion` |  |
| `data.seq` | integer |  |
| `data.hash` | string |  |
| `data.line` | string | The exact canonical JSON line. Its SHA-256 without the hash field is hash. |
| `data.record` | object | The parsed line, in the framework's snake_case field names. |
| `data.created` | boolean |  |