Restore Snapshot Checkpoints and Walk Agent Lineage

The restore endpoints give you complete read access to your agent’s confirmed checkpoint history. You can fetch the latest snapshot by agent ID, retrieve any earlier checkpoint by its exact sequence number for rollbacks or debugging, or list the full lineage chain to reconstruct and verify the parent-hash ancestry. In all cases, the server returns the storage URL pointing to the encrypted ciphertext blob — you download and decrypt it locally using your client key, and independently verify it before trusting it (see Verified Semantic Recall).

GET /snapshot/:agent_id/latest

Retrieve the metadata and storage URL for the most recent confirmed snapshot of a given agent.

GET /snapshot/:agent_id/latest
Authorization: Bearer <TOKEN>

Path Parameters:

Parameter	Type	Description
`agent_id`	string	The agent identifier you supplied on `snapshot()`.

Response — 200 OK

string

UUID of the snapshot record.

string

The agent identifier this snapshot belongs to.

integer

Sequence number of this checkpoint.

string

Storage path (object key) of the ciphertext blob.

integer

Byte size of the stored ciphertext.

integer

Credits debited when this snapshot was uploaded. 0 for free-tier project tokens.

string

Client-supplied payload hash recorded at upload time — re-derive and compare this before trusting the decrypted payload.

string

Confirmation status — "confirmed" for all retrievable snapshots.

string

ISO-8601 timestamp of when this snapshot was confirmed.

string

Public URL you can use to download the ciphertext blob directly from object storage.

{
  "receipt": {
    "snapshot_id": "a1b2c3d4-e5f6-7a8b-9c0d-e1f2a3b4c5d6",
    "agent_id": "4e73b22cf900d744b827e8d7d3d1597f8c159048b65429384f9b4f3b7d1597f8",
    "sequence_number": 12,
    "storage_path": "4e73b22cf900d744b827e8d7d3d1597f8c159048b65429384f9b4f3b7d1597f8/seq-12-84c8a8d11d95.bin",
    "byte_size": 4252,
    "cost_milli": 0,
    "client_payload_hash": "84c8a8d11d95e0cce8da70c1a96c14b7454f738f65429384f9b4f3b7d1597f8c",
    "status": "confirmed",
    "confirmed_at": "2026-06-09T16:45:30.123Z"
  },
  "ciphertextUrl": "https://ksrlmubaxzwufziwarps.supabase.co/storage/v1/object/public/sovseal-rom/4e73b22cf900d744b827e8d7d3d1597f8c159048b65429384f9b4f3b7d1597f8/seq-12-84c8a8d11d95.bin"
}

curl Example

curl -G https://ksrlmubaxzwufziwarps.supabase.co/functions/v1/v2-agent-state/snapshot/4e73b22cf900d744b827e8d7d3d1597f8c159048b65429384f9b4f3b7d1597f8/latest \
  -H "Authorization: Bearer sov_live_YOUR_KEY"

GET /snapshot/:agent_id/:sequence

Retrieve metadata and the storage URL for a checkpoint at a specific sequence number. Use this for rollbacks, audits, or debugging a particular checkpoint in the agent’s history.

GET /snapshot/:agent_id/:sequence
Authorization: Bearer <TOKEN>

Path Parameters:

Parameter	Type	Description
`agent_id`	string	The agent identifier you supplied on `snapshot()`.
`sequence`	integer	Non-negative sequence index to retrieve.

Response — 200 OK

The response schema is identical to GET /snapshot/:agent_id/latest above — a receipt object and a ciphertextUrl. Returns 404 snapshot_not_found if no confirmed snapshot exists at that exact sequence number.

curl Example

curl -G https://ksrlmubaxzwufziwarps.supabase.co/functions/v1/v2-agent-state/snapshot/4e73b22cf900d744b827e8d7d3d1597f8c159048b65429384f9b4f3b7d1597f8/7 \
  -H "Authorization: Bearer sov_live_YOUR_KEY"

GET /snapshot/:agent_id/lineage

Fetch an ordered list of confirmed sequence numbers, payload hashes, and storage paths for an agent. Use this to reconstruct the full parent-hash ancestry chain and verify historical integrity locally.

GET /snapshot/:agent_id/lineage
Authorization: Bearer <TOKEN>

Path Parameters:

Parameter	Type	Description
`agent_id`	string	The agent identifier you supplied on `snapshot()`.

Query Parameters:

Parameter	Type	Required	Description
`limit`	integer	No	Maximum entries to return. Clamped to `[1, 500]`. Default `100`.

Response — 200 OK

Returns a JSON array of lineage entries ordered descending by sequence number (newest first). Note this is a bare array, not wrapped in an object:

integer

Sequence number of this checkpoint entry.

string

Storage path of this checkpoint’s ciphertext blob.

string | null

Storage path of the parent checkpoint, or null for the genesis snapshot.

string

Hash of the payload recorded at upload time.

string

ISO-8601 timestamp of when this snapshot was confirmed.

[
  {
    "sequence_number": 12,
    "storage_path": "4e73b22cf900d744b827e8d7d3d1597f8c159048b65429384f9b4f3b7d1597f8/seq-12-84c8a8d11d95.bin",
    "parent_path": "4e73b22cf900d744b827e8d7d3d1597f8c159048b65429384f9b4f3b7d1597f8/seq-11-f1a2c3b4e5f6.bin",
    "client_payload_hash": "84c8a8d11d95e0cce8da70c1a96c14b7454f738f65429384f9b4f3b7d1597f8c",
    "confirmed_at": "2026-06-09T16:45:30.123Z"
  },
  {
    "sequence_number": 11,
    "storage_path": "4e73b22cf900d744b827e8d7d3d1597f8c159048b65429384f9b4f3b7d1597f8/seq-11-f1a2c3b4e5f6.bin",
    "parent_path": null,
    "client_payload_hash": "f1a2c3b4e5f6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2",
    "confirmed_at": "2026-06-09T16:40:00.000Z"
  }
]

curl Example

curl -G https://ksrlmubaxzwufziwarps.supabase.co/functions/v1/v2-agent-state/snapshot/4e73b22cf900d744b827e8d7d3d1597f8c159048b65429384f9b4f3b7d1597f8/lineage \
  -H "Authorization: Bearer sov_live_YOUR_KEY" \
  --data-urlencode "limit=50"

Get Started

Platform

Agent Plugins

Self-Hosted

Integrations

Cookbooks

API Reference

Release Notes

Restore Snapshot Checkpoints and Walk Agent Lineage

GET /snapshot/:agent_id/latest

Response — 200 OK

curl Example

GET /snapshot/:agent_id/:sequence

Response — 200 OK

curl Example

GET /snapshot/:agent_id/lineage

Response — 200 OK

curl Example

​GET /snapshot/:agent_id/latest

​Response — 200 OK

​curl Example

​GET /snapshot/:agent_id/:sequence

​Response — 200 OK

​curl Example

​GET /snapshot/:agent_id/lineage

​Response — 200 OK

​curl Example

GET /snapshot/:agent_id/latest

Response — 200 OK

curl Example

GET /snapshot/:agent_id/:sequence

Response — 200 OK

curl Example

GET /snapshot/:agent_id/lineage

Response — 200 OK

curl Example