Get cached messages - Talaria Developer Documentation

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>"

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>"

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:

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

string

required

The recipient DID.

string

required

The authorized TalariaCacheService ID.

string

required

The exact public Cache endpoint bound into the signature.

string

required

The authorized Ed25519 verification-method ID.

string

required

The signed timestamp.

string

required

A new replay-resistant nonce.

string

required

Base64 Ed25519 signature over the exact proof text.

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>"

Response

200 Response

{
  "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

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

Straight to the point

GET /cache/messages/{did}

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

Store an encrypted message Get messages for a device

⌘I

​Build the signed proof

​Request

​Response

​After retrieval

​Straight to the point

Build the signed proof

Request

Response

After retrieval

Straight to the point