SiteCall for developers

Calls and texts inside your application.

SiteCall is the phone system: numbers, routing, queues, recordings, transcripts and texting. Your application drives it through a REST API at https://sitecall.ai/api/v1, hears about every change through signed webhooks, and puts calls in your users' browsers and phones with the web and React Native SDKs.

How an application connects

• Your application is registered with SiteCall and manages workspaces (each business you serve). You name a workspace by SiteCall's id or by your own id for it.
• Your backend holds an application key (sc_live_…) and calls the API for its workspaces. The key never reaches a browser or a phone.
• Your users are application users: SiteCall knows them by your own user id. Your backend mints each a 15-minute end-user token (POST /api/v1/sessions); their browser or phone uses that token, and SiteCall checks its workspace and scopes on every request.
• Events come back to your webhook endpoints, signed and in order per call, number or agent.

Credentials

Send it as Authorization: Bearer <credential>. Each operation needs one scope:

numbers:* · routing:* · calls:* · calls:supervise · devices:* · messages:* · media:read · webhooks:* · metrics:read

calls:* is call control and never implies calls:supervise. An end-user token carries at most the scopes the key that minted it holds.

Conventions

• Workspace. Every workspace request names it in x-sitecall-workspace-id. With an application key you may use your own id instead: x-sitecall-external-workspace-id. A key reaches only the workspaces its application manages; a token only its own.
• Idempotency. Every mutation takes an idempotency-key header (1–255 visible ASCII; a UUID is a good choice). The first answer is kept for 24 hours: a retry with the same key and body gets it again with idempotent-replayed: true, the same key with another body is a 422 idempotency_key_reused, and a retry while the first is still running is a 409 idempotency_in_progress. Retry a 503 or a lost answer with the same key: it cannot act twice.
• Pagination. Lists take ?limit= (1–200, default 50) and ?cursor=, newest first, and answer { data, nextCursor }. nextCursor is null on the last page. Cursors are opaque.
• Additive changes only. Within /v1 new fields appear and enum-like values (a state, a role, a kind, an event type, an error code) may take values not listed today. Ignore fields you do not know and treat an unknown value as "other", never as an error.
• Errors. Refusals are { error: { code, message } } with a stable code; routing plan errors add issues. Responses are never cached (cache-control: no-store).
• Browsers. The API answers CORS for every origin (Access-Control-Allow-Origin: *, preflights answer 204), so @sitecall/web can call it from your page. It accepts Authorization, Content-Type, Idempotency-Key, x-sitecall-workspace-id, x-sitecall-external-workspace-id, x-sitecall-application and lets the page read Retry-After, idempotent-replayed, X-Request-Id, X-Vercel-Id. It never allows credentials: a request made without them (the SDK's default) carries no cookies, and a page on another origin can never read an answer to one made with the visitor's cookies. The page authenticates with its end-user token in Authorization. An application key stays on your server.

A refusal

HTTP/1.1 409 Conflict
content-type: application/json

{ "error": { "code": "call_ended", "message": "The call has ended" } }