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>"
}'
Cache API
Acknowledge cached messages
Remove encrypted messages from a Cache after the recipient has safely received them
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>"
}'
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.
Use operation
Build the proof subject
- Trim every message ID.
- Remove blank values.
- Remove duplicates.
- Sort the IDs lexicographically.
- Join them with commas and no spaces.
b, a, and b, the subject is:
a,b
ack in the proof:
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
The Cache endpoint text bound into the signature. Sign the same value you send in the body. For authorization, HTTPS
:443 and a trailing slash are optional; nonstandard ports must match.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>"
}'
Response
200 Response
{
"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
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

