REST reference
The recipient API uses /v1 at the chosen provider, an audience of its own: a token for /mcp
cannot be used against /v1. Every access token is DPoP-bound, for every client: a request carries
Authorization: DPoP plus a DPoP proof, and a token presented as Bearer is refused. Protocol
responses carry Autonym-Version: 1.0. The complete contract is the
generated OpenAPI 3.1 document;
no recipient endpoint is available in the reference service yet.
Routes
| Method | Path | Result |
|---|---|---|
| GET | /.well-known/autonym |
Provider discovery |
| GET | /v1/grant |
Current authenticated grant |
| GET | /v1/domains |
Eligible granted domains and keys, without counts |
| GET | /v1/context |
Signed disclosure, one counted read |
| GET | /v1/context/{domain} |
The same, with conditional-request support |
| POST | /v1/proposals |
Contribution event acknowledgement |
| GET | /v1/proposals/{id} |
Own proposal status only |
| POST | /v1/proposals/{id}/confirm |
Request for exact-statement review |
| DELETE | /v1/proposals/{id} |
Withdraw own proposal |
| GET | /v1/purge-instructions |
At most 100 outstanding signed instructions for this client |
| POST | /v1/purge-instructions/{jti}/ack |
Purge acknowledgement |
Read context
GET /v1/context takes domains, a comma-separated list, and the optional max_level, keys,
declared_only, min_confidence and since. A list has no empty items or duplicates, and a
repeated or unknown parameter fails invalid_request. The provider checks the stored grant, the
current temporal selection and the counter in the same transaction that records the receipt, and a
response has at most 1,000 entries.
A signed response is valid until the earliest of the grant's expiry, an entry's expiry, the next
temporary selection boundary and five minutes after issue. Responses are Cache-Control: no-store,
and nothing may be retained beyond that deadline without an explicit right to keep a copy.
GET /v1/context/{domain} returns an ETag bound to the client, the grant and its revision, the
request and the exact selection. A matching If-None-Match may return 304 only while the earlier
signed object is still valid and the grant still permits it. A 304 is logged and rate-limited but
does not count as a read, and it never extends a deadline.
Contributions and purge
POST /v1/proposals submits one event, of at most 64 KiB, under a separate contribution grant;
retries are identified by the contributor's own event ID. Proposal status and withdrawal are
restricted to the contributor's own events. Other mutating requests need an Idempotency-Key, a
UUIDv4 kept for 30 days; reusing one with a different payload fails idempotency_conflict.
Purge polling and acknowledgement use a separate client lifecycle token, so acknowledgements can continue after a record grant ends. It is valid only on the two purge routes and cannot read context.
Limits
Bodies are at most 64 KiB, and a larger one fails payload_too_large. The default rate ceilings are
60 authorised requests a minute per grant and 600 a minute per client, answered with 429 rate_limited and Retry-After; a provider may lower them. See Errors.
Written against edition 1.0-draft-1: B4 REST binding