POST /snapshot endpoint accepts a fully encrypted agent state checkpoint and registers it as the canonical latest sequence in the replication log. You submit the ciphertext blob, its metadata, and a monotonic sequence number; the server validates the sequence chain, handles billing, uploads the ciphertext to object storage, and returns a confirmed transaction receipt. The server never decrypts or inspects the payload.
Request
Request Body
string
required
An identifier for the agent, chosen and supplied by you — the server does not derive or validate its format beyond treating it as an opaque string. A common convention is
sha256(project_id + ":" + some_stable_identifier).integer
required
Monotonically increasing checkpoint index. Must start at
0 for the genesis snapshot and increment by exactly 1 for each subsequent write.string | null
required
The
storage_path of the immediately preceding snapshot. Must be null when sequence_number is 0. Required and non-null for all subsequent sequences.string
required
64-character SHA-256 hex hash of the security policy. Until policy enforcement is active, use 64 zero characters:
0000000000000000000000000000000000000000000000000000000000000000.string
required
64-character SHA-256 hex hash of the canonicalized payload. Used for Verified Semantic Recall integrity checks and idempotent retry detection.
string
required
Base64-encoded binary ciphertext in the packed
IV || ciphertext || auth_tag format produced by AES-256-GCM.integer
required
Byte length of the decoded ciphertext. Must be greater than
0 and no larger than 262,144 (256 KB, MAX_PAYLOAD_BYTES).string
required
ISO-8601 timestamp generated by the client at the time of snapshot creation.
Example Request Body
Processing Flow
1
JSON & Structural Validation
The server verifies that the request body is valid JSON and that all required fields are present and correctly typed.
2
Sequence Constraints
Sequence
0 requires parent_snapshot to be null. Any sequence greater than 0 requires a non-null parent_snapshot. The submitted sequence number must be exactly latest + 1 — gaps in the sequence chain are rejected with 409 sequence_gap.3
Idempotent Retry Detection
If the submitted sequence number matches the current latest sequence and the
client_payload_hash is identical, the endpoint returns the previously confirmed receipt immediately without re-debiting credits or re-uploading storage.4
Billing Debit
For paid
sov_live_ keys, the server calculates a debit based on byte_size and performs an atomic credit debit. If the balance is insufficient, the request fails with 402 insufficient_credits.5
Storage Upload
The ciphertext is uploaded to the
sovseal-rom bucket at the path: {agent_id}/seq-{sequence_number}-{client_payload_hash[0:12]}.bin.6
Confirmation & Response
On successful upload, the database record status transitions to
confirmed and the server returns a receipt. If storage is unreachable, the record status is set to failed, the credit debit is refunded, and a 503 storage_unavailable error is returned.Response
200 OK
string
UUID of the newly created snapshot record.
string
The 64-character agent hash submitted in the request.
integer
The confirmed sequence number for this checkpoint.
string
The storage path (object key) where the ciphertext blob was written.
integer
Byte size of the confirmed ciphertext as recorded by the server.
integer
Credits debited for this operation in milli-cents.
0 for free-tier project tokens.string
Echo of the
client_payload_hash submitted in the request.string
Confirmation status. Will be
"confirmed" on a successful response.string
ISO-8601 timestamp of when the server confirmed the upload.