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

# Talaria Cache API

> Temporarily store and retrieve encrypted messages for recipients who are not immediately reachable

A Cache is temporary, policy-governed storage for encrypted DDN envelopes. It helps a recipient receive messages after reconnecting without giving the Cache access to plaintext.

## Typical flow

1. A sender or Relay submits an encrypted envelope to `POST /cache/store`.
2. The Cache checks the recipient's public policy and its own endpoint authorization.
3. The recipient signs a short retrieval proof.
4. The recipient calls a messages or chunks endpoint.
5. After safely persisting the encrypted message locally, the recipient acknowledges it.

## Why retrieval needs a proof

Knowing a DID is public information. It must not be sufficient to download that DID's cached messages. Retrieval and acknowledgement use an Ed25519 proof from a verification method authorized by the recipient's `TalariaCacheService`.

The proof binds the operation to:

* Recipient DID and device
* Cache service and exact endpoint
* Authorized key
* Timestamp and one-time nonce
* Requested subject, such as all messages, a chunk group, or sorted message IDs

## Important limitations

Cache response objects currently include a proof model whose `signature` may be `null`. Treat it as event metadata, not a cryptographically verifiable Cache receipt, until node signing is enabled.

## Straight to the point

```text theme={null}
Store: POST /cache/store
Retrieve: GET /cache/messages/{did}[/{deviceId}]
Chunks: GET /cache/chunks/{did}/{messageGroupId}
Delete acknowledged messages: POST /cache/ack
```