Restore & Lineage Endpoints

These endpoints allow clients to pull down historical checkpoints, find the latest state sequence, and fetch public URLs to download encrypted state blobs.

1. Restore Latest Checkpoint

Retrieve the metadata and storage URL for the absolute latest confirmed snapshot of an agent.

Request URL

GET /snapshot/:agent_id/latest

Path Parameters:
- agent_id: The 64-character SHA-256 agent hash identifier.

Response (200 OK)

{
  "receipt": {
    "snapshot_id": "a1b2c3d4-e5f6-7a8b-9c0d-e1f2a3b4c5d6",
    "agent_id": "4e73b22cf900d744b827e8d7d3d1597f8c159048b65429384f9b4f3b7d1597f8",
    "sequence_number": 12,
    "arweave_tx_id": "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"
}

2. Restore by Sequence Number

Retrieve metadata and storage URL for a checkpoint at a specific sequence number, used for rollbacks or debugging.

Request URL

GET /snapshot/:agent_id/:sequence

Path Parameters:
- agent_id: The 64-character SHA-256 agent hash identifier.
- sequence: The non-negative integer sequence index.

Response (200 OK)

Same schema as Restore Latest Checkpoint.

3. Retrieve Lineage Chain

Fetch a list of confirmed sequence numbers, hashes, and storage paths. This enables local vector clients to reconstruct the lineage chain and walk backward to verify history.

Request URL

GET /snapshot/:agent_id/lineage

Path Parameters:
- agent_id: The 64-character SHA-256 agent hash identifier.
Query Parameters:
- limit (optional): Maximum entries to return. Integer between 1 and 500 (default 100).

Response (200 OK)

A JSON array of lineage entries ordered descending by sequence number:

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

Restore & Lineage Endpoints

On this page