> ## 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.

# GET /envelopes: Paginated Encrypted Envelope Retrieval

> Retrieve a paginated, chronologically ordered list of your agent's encrypted envelopes, with IVs split out for direct Web Crypto API decryption.

<style>
  {`
      main, article, .prose {
        margin-left: 2.5cm !important;
        margin-right: 2.5cm !important;
      }
      `}
</style>

The `GET /envelopes` endpoint returns a cursor-paginated list of every encrypted envelope stored in your agent's replication log. To make client-side decryption straightforward with the Web Crypto API, the server strips the initial 12-byte initialization vector (IV) from each stored binary block and returns it as a separate base64 field alongside the remaining ciphertext. You never receive plaintext — only the sealed envelopes your client originally uploaded.

## Request

```http theme={null}
GET /envelopes
Authorization: Bearer <TOKEN>
```

## Query Parameters

<ParamField query="limit" type="integer">
  Maximum number of envelopes to return per page. Minimum `1`, maximum `500`, default `100`.
</ParamField>

<ParamField query="since" type="integer">
  Exclusive lower bound on the sequence number. Returns only envelopes with a sequence number strictly greater than this value. Use the `x-next-cursor` response header value to paginate forward.
</ParamField>

<ParamField query="before" type="integer">
  Exclusive upper bound on the sequence number. Returns only envelopes with a sequence number strictly less than this value.
</ParamField>

## Response Headers

The response includes the following custom headers for cursor-based pagination:

| Header           | Description                                                                                                                                                               |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `x-result-count` | Number of envelopes returned in the current page.                                                                                                                         |
| `x-next-cursor`  | Sequence number of the last envelope on this page. Pass this as `since` in your next request to fetch the following page. Empty when you have reached the end of the log. |

## Response

### 200 OK

Returns a JSON array. Each element represents one encrypted envelope:

<ResponseField name="[].ciphertext" type="string">
  Base64-encoded ciphertext — the AES-256-GCM ciphertext and auth tag, with the IV removed (it is returned separately in `iv`).
</ResponseField>

<ResponseField name="[].iv" type="string">
  Base64-encoded 12-byte GCM initialization vector, extracted from the stored binary block by the server.
</ResponseField>

<ResponseField name="[].clientPayloadHash" type="string">
  SHA-256 hash of the payload as recorded at upload time.
</ResponseField>

<ResponseField name="[].sequenceNumber" type="integer">
  Monotonic sequence number for this envelope.
</ResponseField>

<ResponseField name="[].timestamp" type="string">
  Client-supplied ISO-8601 timestamp from when the envelope was originally created.
</ResponseField>

### Example Response

```json theme={null}
[
  {
    "ciphertext": "YmFzZTY0X2NpcGhlcnRleHRfZXhhbXBsZV93aXRoX2l2X2FuZF9hdXRoX3RhZw==",
    "iv": "MTIzNDU2Nzg5MDEy",
    "clientPayloadHash": "84c8a8d11d95e0cce8da70c1a96c14b7454f738f65429384f9b4f3b7d1597f8c",
    "sequenceNumber": 1,
    "timestamp": "2026-06-09T16:45:30.123Z"
  }
]
```

## curl Example

```bash theme={null}
# Fetch up to 50 envelopes after sequence 0
curl -G https://ksrlmubaxzwufziwarps.supabase.co/functions/v1/v2-agent-state/envelopes \
  -H "Authorization: Bearer sov_live_YOUR_KEY" \
  --data-urlencode "limit=50" \
  --data-urlencode "since=0" \
  -i
# Check x-result-count and x-next-cursor in the response headers to paginate
```