> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sovseal.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Restore Snapshot Checkpoints and Walk Agent Lineage

> Retrieve your agent's latest encrypted snapshot, restore a checkpoint at any sequence number, or walk the full parent lineage chain for history verification.

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](/platform/core-concepts/verified-semantic-recall)).

***

## GET /snapshot/:agent\_id/latest

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

```http theme={null}
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

<ResponseField name="receipt.snapshot_id" type="string">
  UUID of the snapshot record.
</ResponseField>

<ResponseField name="receipt.agent_id" type="string">
  The agent identifier this snapshot belongs to.
</ResponseField>

<ResponseField name="receipt.sequence_number" type="integer">
  Sequence number of this checkpoint.
</ResponseField>

<ResponseField name="receipt.storage_path" type="string">
  Storage path (object key) of the ciphertext blob.
</ResponseField>

<ResponseField name="receipt.byte_size" type="integer">
  Byte size of the stored ciphertext.
</ResponseField>

<ResponseField name="receipt.cost_milli" type="integer">
  Credits debited when this snapshot was uploaded. `0` for free-tier project tokens.
</ResponseField>

<ResponseField name="receipt.client_payload_hash" type="string">
  Client-supplied payload hash recorded at upload time — re-derive and compare this before trusting the decrypted payload.
</ResponseField>

<ResponseField name="receipt.status" type="string">
  Confirmation status — `"confirmed"` for all retrievable snapshots.
</ResponseField>

<ResponseField name="receipt.confirmed_at" type="string">
  ISO-8601 timestamp of when this snapshot was confirmed.
</ResponseField>

<ResponseField name="ciphertextUrl" type="string">
  Public URL you can use to download the ciphertext blob directly from object storage.
</ResponseField>

```json theme={null}
{
  "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

```bash theme={null}
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.

```http theme={null}
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

```bash theme={null}
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.

```http theme={null}
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:

<ResponseField name="[].sequence_number" type="integer">
  Sequence number of this checkpoint entry.
</ResponseField>

<ResponseField name="[].storage_path" type="string">
  Storage path of this checkpoint's ciphertext blob.
</ResponseField>

<ResponseField name="[].parent_path" type="string | null">
  Storage path of the parent checkpoint, or `null` for the genesis snapshot.
</ResponseField>

<ResponseField name="[].client_payload_hash" type="string">
  Hash of the payload recorded at upload time.
</ResponseField>

<ResponseField name="[].confirmed_at" type="string">
  ISO-8601 timestamp of when this snapshot was confirmed.
</ResponseField>

```json theme={null}
[
  {
    "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

```bash theme={null}
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"
```