API
Forty-two endpoints under /v1. The machine-readable contract is docs/openapi.yaml in the repository — generate a client from it if you are not writing TypeScript.
shell
openapi-generator-cli generate -i docs/openapi.yaml -g go -o internal/switchboard
Two behaviours to code against#
A foreign resource is 404, never 403
“Exists but is not yours” would let any project enumerate another’s ids. It protects yours the same way.
401 is deliberately ambiguous
Missing, unknown, revoked and suspended all answer identically, so a suspended project cannot tell which it is. If a working integration starts returning it, check for a suspension before assuming the key is wrong.
Unauthenticated#
| Route | What |
|---|---|
| GET / | What this is, and that everything else needs a key |
| GET /v1/live | Is the process up |
| GET /v1/ready | Can it serve — 503 when Postgres is unreachable |
| GET /v1/about | Build and open-source attribution notice |
Project key#
| Route | What |
|---|---|
| POST /v1/send | Queue a message — 202, accepted not sent |
| GET /v1/messages | This project’s send queue |
| GET /v1/messages/{id} | Did this message arrive |
| GET /v1/pool | Which numbers can send right now, and why the rest cannot |
| POST /v1/instances | Register a number |
| GET /v1/instances/{id}/qr | paired | pending | a code |
| POST /v1/instances/{id}/connect | Pair it — 409 if already connected |
| GET /v1/instances/{id}/number | The registry view of one number |
| POST /v1/instances/{id}/retire | Take it out of service, keep its history |
| GET /v1/usage | sent, rejected, received, pending, dead |
| GET /v1/sends | This project’s outbound attempts |
| GET /v1/deliveries | Its inbound queue and dead letters |
| POST /v1/deliveries/{id}/replay | Replay one of its dead letters |
| GET /v1/audit | Its own trail — including what operators did to it |
Root key#
| Route | What |
|---|---|
| POST /v1/projects | Create a project — webhookSecret shown once |
| POST /v1/projects/{id}/keys | Mint a key — shown once |
| POST /v1/projects/{id}/webhook/rotate | Rotate a leaked secret, and list what must reconnect |
| POST /v1/projects/{id}/disable | Suspend a project |
| GET /v1/admin/instances | The whole deployment on one screen |
| GET /v1/admin/alerts | Six rules — 503 while anything critical fires |
| GET /v1/admin/metrics | Prometheus exposition |
| GET /v1/admin/shards | Which replica holds which number |
| GET /v1/admin/delivery-health | Which numbers are still actually delivering |
| GET /v1/admin/numbers | Every number, every project |
| GET /v1/admin/audit | The cross-project trail |
| POST /v1/admin/sweep | Run one supervisor pass now |
Metrics are behind the root key, unlike most /metrics endpoints
That convention assumes the numbers describe one tenant. These are project names, message volumes and per-project error rates — commercial facts about somebody else’s business.
For AI agents#
llms.txt is the index and docs/llms-full.txt is the complete, self-contained integration guide. It also ships inside the SDK package, so an agent finds it at node_modules/@atrixdigital/switchboard/llms.txt with no network access.