Skip to content
/
Append a superseded value
Last updated

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 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).

POSThttps://api.aitronos.com/v1/sealed-stores/{store}/records/{record_id}/superseded

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 <access token> 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.

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 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

StatusCodeWhen
401AUTHENTICATION_REQUIREDNo access token, or one that is not valid.
403SEALED_STORE_PERSONAL_SESSION_REQUIREDThe call used an API key or a service account. Only a person's own sign-in session reaches a sealed store.
404SEALED_STORE_NOT_FOUNDNo store with that name (details.store).
404SEALED_RECORD_NOT_FOUNDNo record with that id in the caller's store, or its tombstone has passed the 30-day retention.
409SEALED_OPERATION_IN_PROGRESSAn earlier call with this Idempotency-Key has not finished. Retry in a moment.
413SEALED_PAYLOAD_TOO_LARGEpayload is over 64 KiB decoded (details.field, details.max_bytes, details.payload_bytes).
422SEALED_IDEMPOTENCY_KEY_REQUIREDNo Idempotency-Key header.
422SEALED_IDEMPOTENCY_KEY_INVALIDThe Idempotency-Key is not 16 to 128 printable ASCII characters without spaces.
422SEALED_IDEMPOTENCY_KEY_REUSEDThe Idempotency-Key was already used for a different call. Mint a new one for a new change.
422SEALED_PAYLOAD_INVALIDpayload is not standard padded base64, or decodes to fewer than 28 bytes (details.field).
422SEALED_WRAPPED_KEY_INVALIDwrapped_dek is not a wrapped key of the documented shape (details.field).
422SEALED_SUPERSEDED_LIMIT_REACHEDThe record already holds 200 entries, or the store 2,000, within the last 30 days (details.limit; details.scope is record or store).
422VALIDATION_ERRORA body field is missing, of the wrong type or out of range, for example an idempotency_key that does not match its pattern.
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=="
}'

Response:

{
  "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
}
Previous page
Next page