Status and the spec
Two endpoints need no authentication. One tells you the API is up; the other is the full contract as a machine-readable document.
Health
GET/v1/status
curl https://api.agentency.com/v1/status{
"object": "status",
"id": "agentency",
"status": "ok",
"api": "v1",
"version": "2026-08-14"
}No key, no scope. Point an uptime monitor at it.
| Field | Meaning |
|---|---|
object | Always status. |
id | Always agentency. |
status | ok whenever the endpoint answers. |
api | The path version serving the request, v1. |
version | The calendar stamp of the contract, the same value as the Agentency-Version response header. |
A 200 means the API is serving requests. It does not tell you that your key
works, that you have credits, or that a background queue is keeping up. For
those, use GET /v1/me and GET /v1/usage — both need a key, which is the
point.
The per-second burst limit applies here too, counted per IP address because
there is no key, and so does a per-IP minute budget shared with
GET /v1/openapi.json (api_v1_public): a monitor that polls in a tight loop
gets 429 RATE_LIMITED with a Retry-After header. Once a minute is plenty.
If GET /v1/status returns 404 with error.code FEATURE_DISABLED, the
public API is switched off for the deployment you are pointing at rather than
broken. Every other /v1 endpoint answers the same 404 while it is off.
The OpenAPI document
GET/v1/openapi.json
curl https://api.agentency.com/v1/openapi.json -o agentency.jsonThe API serves the committed file byte for byte, with a strong ETag and
Cache-Control: public, max-age=300. Send the ETag back as If-None-Match
and an unchanged document answers 304 Not Modified with no body.
The same document is downloadable from
/developers/openapi.json on this site. That copy
can be fetched cross-origin (Access-Control-Allow-Origin: *) and carries an
ETag, so a tool that re-downloads it can send If-None-Match and get a
304 Not Modified when nothing changed.
It is OpenAPI 3.1 and contains every path, parameter, request body, response
shape and error code, the required scope per operation, the scope catalogue
(x-agentency-scopes), and the webhook event payloads under the top-level
webhooks object.
It is generated from the API's own routes and definitions, and a check fails the build when the committed document drifts from the code. An endpoint or field that is not in it is not part of the contract. The reference pages on this site are rendered from the same file.
What to do with it
- Import it into Postman, Insomnia, Bruno or any OpenAPI 3.1 client to get a complete request collection.
- Generate a typed client for a language we do not ship an SDK for.
- Diff it between releases to see precisely what changed.
- Point contract tests at it so your integration fails loudly when a shape you depend on moves.
Both official SDKs generate their endpoint tables from this document, so a client you generate yourself is working from exactly the same source — not a copy that lags behind it.
What's next
- Versioning — how the contract changes over time.
- SDKs — clients we already generate.
- Support — when the health check is green and it still is not working.