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

MethodPathWhat it does
GET, POST/api/v1/tenantsList and create tenants
GET, PATCH/api/v1/tenants/{id}Read a tenant; change its tone, transfer number and options
POST/api/v1/tenants/{id}/provisionCreate or refresh the receptionist
POST/api/v1/tenants/{id}/numberGet a US or Canadian number (live only, limited)
GET/api/v1/numbers/searchSearch available numbers (free)
GET, PUT/api/v1/connectorYour booking connector
POST/api/v1/connector/testRun the conformance test
GET, POST, DELETE/api/v1/webhook_endpointsWebhook endpoints
GET/api/v1/webhook_deliveriesDelivery log; POST .../{id}/replay to send again
GET/api/v1/callsCalls, newest first; /calls/{id} for one with its transcript
GET/api/v1/usageUsage by day range and tenant

The full description, with request and response shapes, is in the OpenAPI file.

Next: Webhooks.