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
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).Monotonically increasing checkpoint index. Must start at
0 for the genesis snapshot and increment by exactly 1 for each subsequent write.The
storage_path of the immediately preceding snapshot. Must be null when sequence_number is 0. Required and non-null for all subsequent sequences.64-character SHA-256 hex hash of the security policy. Until policy enforcement is active, use 64 zero characters:
0000000000000000000000000000000000000000000000000000000000000000.64-character SHA-256 hex hash of the canonicalized payload. Used for Verified Semantic Recall integrity checks and idempotent retry detection.
Base64-encoded binary ciphertext in the packed
IV || ciphertext || auth_tag format produced by AES-256-GCM.Byte length of the decoded ciphertext. Must be greater than
0 and no larger than 262,144 (256 KB, MAX_PAYLOAD_BYTES).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.