Verified by the sovseal team
POST /snapshot
Upload a client-encrypted state snapshot checkpoint.
This endpoint accepts a base64-encoded encrypted snapshot envelope representing the entire state of an agent. It enforces monotonic sequence numbering, handles platform billing debits, uploads the ciphertext to storage, and returns a transaction receipt.
Request URL
POST /snapshotRequest Body Schema
The body must be a JSON object with the following fields:
| Field | Type | Required | Description |
|---|---|---|---|
agent_id | string | Yes | SHA-256 hash (64 characters) identifying the agent, derived from project ID and encryption key. |
sequence_number | integer | Yes | Monotonically increasing checkpoint index (starting at 0 for genesis). |
parent_snapshot | string | null | Yes | The arweave_tx_id (or path ID) of the parent snapshot. Must be null for sequence 0. |
policy_hash | string | Yes | SHA-256 hash of the security policy (defaults to 64 zeros 0000... until policy enforcement). |
client_payload_hash | string | Yes | SHA-256 hash of the canonicalized payload (used for Verified Semantic Recall verification). |
ciphertext_b64 | string | Yes | Base64-encoded binary ciphertext (packed AES-256-GCM `IV |
byte_size | integer | Yes | Byte length of the decoded ciphertext. Must be $> 0$ and $\le 10,485,760$ (10 MB). |
timestamp | string | Yes | ISO-8601 timestamp generated by the client. |
Example Request Body
{
"agent_id": "4e73b22cf900d744b827e8d7d3d1597f8c159048b65429384f9b4f3b7d1597f8",
"sequence_number": 0,
"parent_snapshot": null,
"policy_hash": "0000000000000000000000000000000000000000000000000000000000000000",
"client_payload_hash": "84c8a8d11d95e0cce8da70c1a96c14b7454f738f65429384f9b4f3b7d1597f8c",
"ciphertext_b64": "YmFzZTY0X2NpcGhlcnRleHRfZXhhbXBsZV93aXRoX2l2X2FuZF9hdXRoX3RhZw==",
"byte_size": 42,
"timestamp": "2026-06-09T16:45:30.000Z"
}Processing Flow
- JSON & Structural Validation: Verifies that the JSON shape is correct and that all required fields are present.
- Sequence Constraints:
- Sequence
0requiresparent_snapshotto benull. - Sequence $> 0$ requires
parent_snapshotto be non-null. - The sequence number must be exactly
latest + 1(preventing sequence gaps).
- Sequence
- Idempotent Retries: If the sequence number matches the latest sequence number in the database, and the
client_payload_hashis identical, the endpoint returns the prior confirmed receipt immediately without debiting credits or re-uploading storage. - Billing Debit: For paid API keys (
sov_live_), the system calculates a debit cost based onbyte_sizeand executes an atomic credit debit. If the balance is insufficient, a402 insufficient_creditserror is thrown. - Storage Upload: Ciphertext is uploaded to the public
sovseal-rombucket at:{agent_id}/seq-{sequence_number}-{client_payload_hash.slice(0, 12)}.bin - Confirmation & Response: Upon successful upload, the database record status changes to
confirmedand a receipt is returned. If storage fails, the database row is updated tofailed, the credit debit is refunded, and a503 storage_unavailableerror is returned.
Response Schema (200 OK)
A JSON receipt object confirming checkpoint registration:
{
"snapshot_id": "a1b2c3d4-e5f6-7a8b-9c0d-e1f2a3b4c5d6",
"agent_id": "4e73b22cf900d744b827e8d7d3d1597f8c159048b65429384f9b4f3b7d1597f8",
"sequence_number": 0,
"arweave_tx_id": "4e73b22cf900d744b827e8d7d3d1597f8c159048b65429384f9b4f3b7d1597f8/seq-0-84c8a8d11d95.bin",
"byte_size": 42,
"cost_milli": 0,
"client_payload_hash": "84c8a8d11d95e0cce8da70c1a96c14b7454f738f65429384f9b4f3b7d1597f8c",
"status": "confirmed",
"confirmed_at": "2026-06-09T16:45:31.123Z"
}