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

# Get cached messages

> Retrieve pending encrypted envelopes for a recipient using a signed Cache access proof

This endpoint returns encrypted messages waiting for one recipient DID. It does not decrypt them.

Because a DID is public, the DID alone is not authorization. Your client must sign a Cache retrieval proof with an Ed25519 verification method authorized by the recipient's `TalariaCacheService`.

## Build the signed proof

Construct this exact UTF-8 string. Do not add a trailing newline:

```text theme={null}
talaria:cache:retrieval-proof:v1
operation=pull
did=did:talaria:1111111111111111111111
device_id=
service_id=did:talaria:1111111111111111111111#cache
cache_endpoint=https://cache.example.com
key_id=did:talaria:1111111111111111111111#signing
timestamp=2026-07-24T16:30:00Z
nonce=<unique-random-nonce>
subject=*
```

Sign those bytes with the authorized Ed25519 private key, then Base64-encode the signature.

The timestamp may be ISO-8601, epoch milliseconds, or epoch seconds and must fall within the Cache's permitted clock skew. Never reuse a nonce with the same operation, DID, and key.

## Request

<ParamField path="did" type="string" required>
  The recipient DID.
</ParamField>

<ParamField header="X-Service-Id" type="string" required>
  The authorized `TalariaCacheService` ID.
</ParamField>

<ParamField header="X-Cache-Endpoint" type="string" required>
  The exact public Cache endpoint bound into the signature.
</ParamField>

<ParamField header="X-Key-Id" type="string" required>
  The authorized Ed25519 verification-method ID.
</ParamField>

<ParamField header="X-Timestamp" type="string" required>
  The signed timestamp.
</ParamField>

<ParamField header="X-Nonce" type="string" required>
  A new replay-resistant nonce.
</ParamField>

<ParamField header="X-Signature" type="string" required>
  Base64 Ed25519 signature over the exact proof text.
</ParamField>

<RequestExample>
  ```bash Request theme={null}
  curl --request GET \
    --url "https://cache.example.com/cache/messages/did%3Atalaria%3A1111111111111111111111" \
    --header "X-Service-Id: did:talaria:1111111111111111111111#cache" \
    --header "X-Cache-Endpoint: https://cache.example.com" \
    --header "X-Key-Id: did:talaria:1111111111111111111111#signing" \
    --header "X-Timestamp: 2026-07-24T16:30:00Z" \
    --header "X-Nonce: <unique-random-nonce>" \
    --header "X-Signature: <base64-signature>"
  ```
</RequestExample>

## Response

```json 200 Response theme={null}
{
  "count": 1,
  "messages": [
    {
      "message_id": "9f8d6f08-bce5-4df5-b22b-bf8c6bd4e143",
      "recipient": "did:talaria:1111111111111111111111",
      "expires_at": "2026-07-25T16:30:00Z",
      "chunked": false,
      "envelope": {
        "message_id": "9f8d6f08-bce5-4df5-b22b-bf8c6bd4e143",
        "to": "did:talaria:1111111111111111111111",
        "payload": {"ciphertext_b64":"<encrypted-message>"}
      },
      "proof": {
        "event_type": "retrieval",
        "signature": null
      }
    }
  ]
}
```

## After retrieval

1. Verify the envelope and any sender signature your application requires.
2. Store it safely on the recipient device.
3. Decrypt it locally.
4. Acknowledge it only after you no longer need the Cache copy.

## Straight to the point

```http theme={null}
GET /cache/messages/{did}
```

Proof operation: `pull`\
Proof device: empty\
Proof subject: `*`