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

# Acknowledge cached messages

> Remove encrypted messages from a Cache after the recipient has safely received them

Acknowledgement tells the Cache that it may remove specific messages for a recipient. Call it only after your client has safely stored or processed the returned encrypted envelopes.

This is not a read receipt for the sender. It is a recipient-authorized Cache deletion.

## Build the proof subject

1. Trim every message ID.
2. Remove blank values.
3. Remove duplicates.
4. Sort the IDs lexicographically.
5. Join them with commas and no spaces.

For IDs `b`, `a`, and `b`, the subject is:

```text theme={null}
a,b
```

Use operation `ack` in the proof:

```text theme={null}
talaria:cache:retrieval-proof:v1
operation=ack
did=did:talaria:1111111111111111111111
device_id=mobile-01
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=3c7a...-uuid,9f8d...-uuid
```

## Request

<ParamField body="did" type="string" required>
  Recipient DID that owns the cached messages.
</ParamField>

<ParamField body="message_ids" type="string[]" required>
  Message UUIDs to remove.
</ParamField>

<ParamField body="device_id" type="string">
  Device bound into the proof.
</ParamField>

<ParamField body="service_id" type="string" required>
  Authorized Cache service ID.
</ParamField>

<ParamField body="cache_endpoint" type="string" required>
  Exact Cache endpoint.
</ParamField>

<ParamField body="key_id" type="string" required>
  Authorized Ed25519 verification method.
</ParamField>

<ParamField body="timestamp" type="string" required>
  Signed timestamp.
</ParamField>

<ParamField body="nonce" type="string" required>
  New one-time nonce.
</ParamField>

<ParamField body="signature_b64" type="string" required>
  Base64 Ed25519 signature over the exact proof.
</ParamField>

<RequestExample>
  ```bash Request theme={null}
  curl --request POST \
    --url "https://cache.example.com/cache/ack" \
    --header "Content-Type: application/json" \
    --data '{
      "did": "did:talaria:1111111111111111111111",
      "device_id": "mobile-01",
      "message_ids": [
        "3c7adff0-151e-432f-a101-44c7351f654a",
        "9f8d6f08-bce5-4df5-b22b-bf8c6bd4e143"
      ],
      "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>",
      "signature_b64": "<base64-signature>"
    }'
  ```
</RequestExample>

## Response

```json 200 Response theme={null}
{
  "acked": 2,
  "message_ids": [
    "3c7adff0-151e-432f-a101-44c7351f654a",
    "9f8d6f08-bce5-4df5-b22b-bf8c6bd4e143"
  ]
}
```

`acked` may be smaller than the submitted array if some IDs were already absent.

## Straight to the point

```http theme={null}
POST /cache/ack
```

* Proof operation: `ack`
* Proof subject: sorted, unique, comma-joined message IDs
* Effect: removes acknowledged Cache entries