HTTP API

Base path

https://<relay host>/v1/<app id>/mailbox/<mailbox name>

• <app id> is a registered UUIDv7 in lowercase: ^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$.
• <mailbox name> is the mailbox id in lowercase hex: ^[0-9a-f]{32}$.
• <dir> below is p2c or c2p.
• <seq> is a decimal sequence number from 1 to 2^64 - 1, with no leading zeros.

An unknown app id, a malformed mailbox name, the bare host and every path outside this tree answer the same 404. A client cannot tell an unregistered app from a typo, and a scanner learns nothing about which apps a relay serves.

Authentication

Every request carries:

Authorization: Bearer <bearer>

where <bearer> is the 43-character base64url token from Keys and derivation. A missing or malformed bearer gets 401 before the mailbox is consulted. On a WebSocket upgrade, a browser may send the bearer as a subprotocol instead; see Watch.

The token is never a cookie, and the relay sets no cookies.

Endpoints

Paths in the table are relative to /v1/<app id>.

Claim

PUT /v1/<app>/mailbox/<id>
Authorization: Bearer <bearer>
Content-Type: application/json

{"tokenDigest": "<token digest>"}

The first bearer to claim a mailbox owns it. The body must name the SHA-256 of the bearer being presented, as lowercase hex. This guards against a client with a bug locking a mailbox under a token it cannot reproduce: if the digest does not match the bearer, the relay answers 400 and claims nothing.

Claiming is idempotent. Both devices of a link may claim; the second one gets 204. A claim restarts the 30-day idle timer.

Every other request to a mailbox that has not been claimed answers 401.

Erase

DELETE /v1/<app>/mailbox/<id>

Deletes both directions, the stored digest and the idle timer, and closes every watcher with close code 1000 and reason erased. Answers 204. The next claim, by any token, starts afresh.

Store an envelope

PUT /v1/<app>/mailbox/<id>/<dir>/<seq>
Content-Type: application/octet-stream

<envelope bytes>

The relay checks, without opening the envelope:

On success it stores the envelope, records <seq> as the direction's last sequence, restarts the idle timer, notifies watchers of the direction and answers 201.

A <seq> that is not a valid sequence number answers 404. Any method other than PUT on this path answers 405 with Allow: PUT.

Fetch

GET /v1/<app>/mailbox/<id>/<dir>?after=<seq>&limit=<n>

Answers 200 with Content-Type: application/octet-stream and the wire body holding up to limit envelopes, oldest first.

An empty result is a 200 with the body 00000000.

Last sequence

HEAD /v1/<app>/mailbox/<id>/<dir>

Answers 200 with X-Relay-Last: <seq>, the highest sequence ever stored in the direction, or no such header if nothing was ever stored. The value survives pruning, so a sender that lost its state can continue from it.

Prune

DELETE /v1/<app>/mailbox/<id>/<dir>?through=<seq>

Deletes every envelope in the direction with a sequence up to and including through. Answers 204, also when there was nothing to delete. through is required; a missing or invalid value answers 400. Pruning does not change X-Relay-Last and does not restart the idle timer.

Watch

GET /v1/<app>/mailbox/<id>/<dir>/watch upgrades to a WebSocket. A request without Upgrade: websocket answers 426. See Watch WebSocket.

Other methods

On the mailbox path, methods other than PUT and DELETE answer 405 with Allow: PUT, DELETE. On a direction path, methods other than GET, HEAD and DELETE answer 405 with Allow: GET, HEAD, DELETE. A direction other than p2c or c2p answers 404.

Wire body

A fetch response packs envelopes back to back:

count (UInt32 BE)                          at most 64
repeat count times:
    length (UInt32 BE) ‖ envelope (length bytes)

A client must reject a body that:

• is shorter than 4 bytes;
• has a count above 64;
• has an envelope length above 1 MiB + 38 or beyond the end of the body;
• has bytes left over after the last envelope.

The relay never returns more than 16 envelopes; the limit of 64 is what a client accepts.

Errors

Every error has a small JSON body. Clients act on the status code alone.

{"error": "sequence_conflict", "status": 409}

The SDKs fold these into a few codes:

Response headers

Every response carries:

Cache-Control: no-store
X-Content-Type-Options: nosniff
Referrer-Policy: no-referrer
Access-Control-Allow-Origin: *
Access-Control-Expose-Headers: X-Relay-Last, X-Relay-More

A preflight OPTIONS on any valid path also gets:

Access-Control-Allow-Methods: GET, HEAD, PUT, DELETE
Access-Control-Allow-Headers: Authorization, Content-Type
Access-Control-Max-Age: 86400

Allowing every origin is safe because authority comes only from the bearer header. A page that does not hold the token gets 401.

Concurrency

The relay handles requests to one mailbox one at a time, in arrival order. Two writes racing for the same sequence resolve cleanly: one gets 201, the other 409. Different mailboxes do not wait for each other.

A full exchange with curl

The bearer and digest below come from credential set 0 of the test vectors. The envelope is that set's first envelope. Set APP to an app id registered on your relay.

BASE=http://127.0.0.1:8080/v1/$APP/mailbox/41fa13c183c0c2092a085390c172cba1
AUTH="Authorization: Bearer 16Lm3t_PFz5tqDn_w8cIkbkUtj8zrxVcMgO4_qSNX74"

# Claim
curl -i -X PUT "$BASE" -H "$AUTH" -H 'Content-Type: application/json' \
  -d '{"tokenDigest":"8da1975827ae6db05a1f3be74348c315975316e3e10c22b12abfa2febc7d8b51"}'

# Store envelope 1 (hex from vectors.json, envelopes[0].envelope)
echo -n "<envelope hex>" | xxd -r -p > env1.bin
curl -i -X PUT "$BASE/p2c/1" -H "$AUTH" -H 'Content-Type: application/octet-stream' \
  --data-binary @env1.bin

# Last sequence
curl -I "$BASE/p2c" -H "$AUTH"

# Fetch and show the wire body
curl -s "$BASE/p2c?after=0&limit=16" -H "$AUTH" | xxd | head

# Prune and erase
curl -i -X DELETE "$BASE/p2c?through=1" -H "$AUTH"
curl -i -X DELETE "$BASE" -H "$AUTH"