# Append a superseded value Keeps one sealed value that a merge discarded, such as the name that lost a rename on another device, so the person can still recover it. It is allowed on a deleted record too, since a merge can lose a value to a delete. **Idempotent on the body's `idempotency_key`.** Appending the same key to the same record again answers the stored entry with `200 OK` and stores nothing. The answer is the entry without its sealed content; the [list read](/docs/api-reference/sealed-stores/list-superseded) carries it. Entries are kept 30 days, at most 200 per record and 2,000 per store, each at most 64 KiB decoded. When either log is full the append is refused with `422 SEALED_SUPERSEDED_LIMIT_REACHED` (`details.scope` says which); nothing is dropped to make room, because every entry is a value the person may still want back. Also requires an `Idempotency-Key` header, like every write: re-sending the same header answers the first call's exact response (`Idempotent-Replayed: true`). #### Path Parameters **`store`** string required The store: `aitronos-browser`. Up to 64 characters; an unknown store is `404 SEALED_STORE_NOT_FOUND`. **`record_id`** string required The record's id, as the client minted it: 16 to 128 characters of `A-Z a-z 0-9 _ -`. #### Headers **`Authorization`** string required `Bearer ` from the person's own sign-in. API keys and service accounts are refused with `403 SEALED_STORE_PERSONAL_SESSION_REQUIRED`. **`Idempotency-Key`** string required A random id minted once for this change and sent again on every retry of it: 16 to 128 printable ASCII characters, no spaces (a UUID works). The first accepted answer is remembered for 30 days; see [Idempotency-Key](/docs/api-reference/sealed-stores/introduction#idempotency-key). #### Body Parameters **`idempotency_key`** string required An opaque key the client computes for the value, for example a keyed digest of it: 16 to 128 printable ASCII characters, no spaces. The same value gives the same key even though its ciphertext differs every time it is sealed. **`schema_version`** integer required The client's schema and sealing version for this value, 1 to 2,147,483,647. Stored and returned as sent; the server never interprets it. **`device_id`** string required The writing device's id: the device id this device signed in with. 16 to 255 characters of `A-Z a-z 0-9 . _ : @ -`. **`wrapped_dek`** object or null optional The entry's own wrapped data key (`v`, `aead`, `nonce`, `ct`, `epk`, the same shape as a record's), or `null` when the entry is sealed under its record's data key. Defaults to `null`. **`payload`** string required The sealed value, standard padded base64. At least 28 bytes and at most 64 KiB (65,536 bytes) decoded. ## Returns `201 Created` with the new entry, or `200 OK` with the entry already kept under this `idempotency_key`. Neither carries the sealed content; [List superseded values](/docs/api-reference/sealed-stores/list-superseded) does. - **`object`** string — `sealed_superseded_envelope`. - **`id`** string — the entry's id (`sealsup_` and 32 hex characters). - **`record_id`** string — the record it belongs to. - **`idempotency_key`** string — as sent. - **`schema_version`** integer — as sent. - **`device_id`** string — the device that appended it. - **`created_at`** string — when it was kept (ISO 8601 UTC). - **`payload_bytes`** integer — the decoded size of its payload. Every answer carries the header **`Idempotent-Replayed`**: `false` on the first answer, `true` when this is the remembered answer to an `Idempotency-Key` sent before. ## Errors | Status | Code | When | | --- | --- | --- | | 401 | `AUTHENTICATION_REQUIRED` | No access token, or one that is not valid. | | 403 | `SEALED_STORE_PERSONAL_SESSION_REQUIRED` | The call used an API key or a service account. Only a person's own sign-in session reaches a sealed store. | | 404 | `SEALED_STORE_NOT_FOUND` | No store with that name (`details.store`). | | 404 | `SEALED_RECORD_NOT_FOUND` | No record with that id in the caller's store, or its tombstone has passed the 30-day retention. | | 409 | `SEALED_OPERATION_IN_PROGRESS` | An earlier call with this `Idempotency-Key` has not finished. Retry in a moment. | | 413 | `SEALED_PAYLOAD_TOO_LARGE` | `payload` is over 64 KiB decoded (`details.field`, `details.max_bytes`, `details.payload_bytes`). | | 422 | `SEALED_IDEMPOTENCY_KEY_REQUIRED` | No `Idempotency-Key` header. | | 422 | `SEALED_IDEMPOTENCY_KEY_INVALID` | The `Idempotency-Key` is not 16 to 128 printable ASCII characters without spaces. | | 422 | `SEALED_IDEMPOTENCY_KEY_REUSED` | The `Idempotency-Key` was already used for a different call. Mint a new one for a new change. | | 422 | `SEALED_PAYLOAD_INVALID` | `payload` is not standard padded base64, or decodes to fewer than 28 bytes (`details.field`). | | 422 | `SEALED_WRAPPED_KEY_INVALID` | `wrapped_dek` is not a wrapped key of the documented shape (`details.field`). | | 422 | `SEALED_SUPERSEDED_LIMIT_REACHED` | The record already holds 200 entries, or the store 2,000, within the last 30 days (`details.limit`; `details.scope` is `record` or `store`). | | 422 | `VALIDATION_ERROR` | A body field is missing, of the wrong type or out of range, for example an `idempotency_key` that does not match its pattern. | ```bash cURL curl -X POST "https://api.aitronos.com/v1/sealed-stores/aitronos-browser/records/vSWmWbg9sDur336pnYgYzQ/superseded" \ -H "Authorization: Bearer $ACCESS_TOKEN" \ -H "Idempotency-Key: d20c67e1-5a91-473d-be6d-0b5d0527a5b8" \ -H "Content-Type: application/json" \ -d '{ "idempotency_key": "_L-GAnevXC-zPLB0ZuEDXbvnEAUx-Xu3qqUsPYEptYo", "schema_version": 1, "device_id": "1aee2c02-ccac-4ede-b017-1334be895e2e", "wrapped_dek": null, "payload": "kwzYjhH7rTGITjOzIhiW8zdwJbbx/yp8+Sb5pCJ3FLqWaw66/CGT5Q==" }' ``` ```python Python import os import uuid import requests idempotency_key = str(uuid.uuid4()) # once per change; reuse it on every retry # The body's idempotency_key identifies the VALUE (for example a keyed digest # of it), so the same lost value is kept once however often it is appended. # The Idempotency-Key header identifies this CALL, like on every write. entry = { "idempotency_key": "_L-GAnevXC-zPLB0ZuEDXbvnEAUx-Xu3qqUsPYEptYo", "schema_version": 1, "device_id": "1aee2c02-ccac-4ede-b017-1334be895e2e", "wrapped_dek": None, "payload": "kwzYjhH7rTGITjOzIhiW8zdwJbbx/yp8+Sb5pCJ3FLqWaw66/CGT5Q==" } response = requests.post( "https://api.aitronos.com/v1/sealed-stores/aitronos-browser/records/vSWmWbg9sDur336pnYgYzQ/superseded", headers={ "Authorization": f"Bearer {os.environ['AITRONOS_TOKEN']}", "Idempotency-Key": idempotency_key, }, json=entry, timeout=30, ) body = response.json() if response.status_code in (200, 201): # 201: kept. 200: this idempotency_key was already kept; nothing new was stored. print("entry", body["id"], "kept at", body["created_at"]) else: print(response.status_code, body["error"]["code"], body["error"]["details"]) ``` ```javascript JavaScript const idempotencyKey = crypto.randomUUID(); // once per change; reuse it on every retry // The body's idempotency_key identifies the VALUE; the header identifies this CALL. const entry = { "idempotency_key": "_L-GAnevXC-zPLB0ZuEDXbvnEAUx-Xu3qqUsPYEptYo", "schema_version": 1, "device_id": "1aee2c02-ccac-4ede-b017-1334be895e2e", "wrapped_dek": null, "payload": "kwzYjhH7rTGITjOzIhiW8zdwJbbx/yp8+Sb5pCJ3FLqWaw66/CGT5Q==" }; const response = await fetch("https://api.aitronos.com/v1/sealed-stores/aitronos-browser/records/vSWmWbg9sDur336pnYgYzQ/superseded", { method: "POST", headers: { Authorization: `Bearer ${process.env.AITRONOS_TOKEN}`, "Content-Type": "application/json", "Idempotency-Key": idempotencyKey, }, body: JSON.stringify(entry), }); const body = await response.json(); if (response.ok) { console.log("entry", body.id, "kept at", body.created_at); } else { console.log(response.status, body.error.code, body.error.details); } ``` **Response:** 201 Created ```json { "object": "sealed_superseded_envelope", "id": "sealsup_3f3a0c50a8b1db8814d48a98ada6a0d1", "record_id": "vSWmWbg9sDur336pnYgYzQ", "idempotency_key": "_L-GAnevXC-zPLB0ZuEDXbvnEAUx-Xu3qqUsPYEptYo", "schema_version": 1, "device_id": "1aee2c02-ccac-4ede-b017-1334be895e2e", "created_at": "2026-10-10T09:02:45.120774Z", "payload_bytes": 40 } ``` 422 Log full ```json { "success": false, "error": { "code": "SEALED_SUPERSEDED_LIMIT_REACHED", "message": "This item has kept as many replaced values as it can.", "system_message": "the record holds 200 superseded entries, the most allowed", "type": "validation_error", "status": 422, "details": { "limit": 200, "scope": "record" }, "trace_id": "73b044e1-8cd8-47da-91a9-84588b15b361", "timestamp": "2026-10-10T09:06:31.927350Z" } } ``` 404 Not found ```json { "success": false, "error": { "code": "SEALED_RECORD_NOT_FOUND", "message": "That item isn't synced.", "system_message": "no record with this id in this store", "type": "client_error", "status": 404, "details": {}, "trace_id": "8072201e-2670-4016-b6f6-2fd0e7a359ef", "timestamp": "2026-10-10T09:07:02.394118Z" } } ``` ## Related Resources - [Sealed stores](/docs/api-reference/sealed-stores/introduction) - [List superseded values](/docs/api-reference/sealed-stores/list-superseded) - [Update a sealed record](/docs/api-reference/sealed-stores/update-record) - [Get a sealed record](/docs/api-reference/sealed-stores/get-record)