API basics
Authentication
Send your key as a bearer token. Keys are created in the developer console and shown once; Sanaa stores only a hash.
Authorization: Bearer sk_test_... (or sk_live_...)Test and live
A test key only sees and changes test tenants. A live key only sees live tenants. They never mix, and webhook endpoints are separate too: test endpoints get events from test tenants, live endpoints from live tenants.
Scopes
Each key carries scopes: tenants:read, tenants:write, calls:read, calls:transcripts, usage:read, webhooks:write, connector:write. Give a key only what it needs. Transcripts need their own scope.
Errors
Errors use one shape, and every response carries a Sanaa-Request-Id header. Quote the request id if you contact us.
{ "error": { "type": "invalid_request", "message": "external_id is required...", "request_id": "req_..." } }Idempotency
Creating a tenant with the same external_id returns the existing tenant. Provisioning can be repeated safely. Requests Sanaa sends to your connector carry an Idempotency-Key so a retried booking never duplicates.
Endpoints
| Method | Path | What it does |
|---|---|---|
| GET, POST | /api/v1/tenants | List and create tenants |
| GET, PATCH | /api/v1/tenants/{id} | Read a tenant; change its tone, transfer number and options |
| POST | /api/v1/tenants/{id}/provision | Create or refresh the receptionist |
| POST | /api/v1/tenants/{id}/number | Get a US or Canadian number (live only, limited) |
| GET | /api/v1/numbers/search | Search available numbers (free) |
| GET, PUT | /api/v1/connector | Your booking connector |
| POST | /api/v1/connector/test | Run the conformance test |
| GET, POST, DELETE | /api/v1/webhook_endpoints | Webhook endpoints |
| GET | /api/v1/webhook_deliveries | Delivery log; POST .../{id}/replay to send again |
| GET | /api/v1/calls | Calls, newest first; /calls/{id} for one with its transcript |
| GET | /api/v1/usage | Usage by day range and tenant |
The full description, with request and response shapes, is in the OpenAPI file.
Next: Webhooks.