> ## Documentation Index
> Fetch the complete documentation index at: https://docs.openpayload.io/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.

Acknowledgement applies only to the Cache receiving this request. A recipient should acknowledge the message at each Cache from which it actually retrieves a copy. A response from one Cache does not purge other replicas.

## 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}
openpayload:cache:retrieval-proof:v1
operation=ack
did=did:openpayload:1111111111111111111111
device_id=mobile-01
service_id=did:openpayload:1111111111111111111111#cache
cache_endpoint=https://cache.example.com
key_id=did:openpayload:1111111111111111111111#signing
timestamp=<current-RFC3339-timestamp>
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:openpayload:1111111111111111111111",
      "device_id": "mobile-01",
      "message_ids": [
        "3c7adff0-151e-432f-a101-44c7351f654a",
        "9f8d6f08-bce5-4df5-b22b-bf8c6bd4e143"
      ],
      "service_id": "did:openpayload:1111111111111111111111#cache",
      "cache_endpoint": "https://cache.example.com",
      "key_id": "did:openpayload:1111111111111111111111#signing",
      "timestamp": "<current-RFC3339-timestamp>",
      "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.

For replicated delivery, track acknowledgement by the Cache endpoint used for each retrieval. Retry a failed acknowledgement while that endpoint still holds the copy and before `expires_at`. Never assume another Cache forwarded the acknowledgement, and do not assume the Cache must retain a copy until its upper-bound expiration.

## Straight to the point

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

* Proof operation: `ack`
* Proof subject: sorted, unique, comma-joined message IDs
* Effect: removes acknowledged entries from this Cache only
* Replicas: acknowledge each Cache from which the recipient retrieves a copy


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.