Voice sessions API
Create, inspect and end an audio session, or approve a pending tool action with scoped keys.
These endpoints create browser audio sessions, not outbound PSTN dialing. You need a published voice assistant, working providers, applicable balances and capacity. Use the browser SDK for a complete microphone interface.
Find an assistant
Send GET /api/v1/agents with an API key carrying agents:read. The response contains organizationId and an agents array with each available assistant's id, name and type. Public keys list only their permitted assistant IDs. Use the returned id when creating a session; listing an assistant does not prove its voice stack is ready.
Create a session
POST /api/v1/calls uses Authorization: Bearer YOUR_API_KEY and JSON:
{
"id": "YOUR_PUBLISHED_ASSISTANT_UUID",
"browserId": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
"remember": false,
"artifactConsent": false,
"variables": {}
}The browser ID above illustrates the format. Generate your own 32 random bytes encoded as 64 lowercase hexadecimal characters for a client identity; do not reuse the example across visitors.
| Field | Requirement |
|---|---|
id | Assistant UUID in the key's organisation. |
browserId | Exactly 64 lowercase hex characters. |
remember | Optional boolean, default false; request persistent facts only with the user's consent. |
artifactConsent | Optional boolean, default false; recording and analysis still depend on assistant configuration. |
variables | Optional string-value object, default empty. Overrides require a private key and defined prompt variables. |
Public creation requires an allowed Origin and assistant ID. The response contains:
{
"id": "CALL_UUID",
"token": "CALL_CONTROL_TOKEN",
"roomToken": "LIVEKIT_ROOM_TOKEN",
"url": "wss://YOUR_AUDIO_HOST",
"expiresAt": "2026-10-11T12:05:00.000Z"
}Join the returned audio service with roomToken, or let the SDK do it. Treat session tokens as sensitive and keep them out of URLs/logs. Call creation is not idempotent: an uncertain successful POST must not be automatically repeated.
Inspect or end a session
| Method and path | Private scope | Result |
|---|---|---|
GET /api/v1/calls/{callId} | calls:read | State, failure, ended flag and revision; private access also includes end reason, metrics, retained outputs and version ID. |
DELETE /api/v1/calls/{callId} | calls:control | Ends the session and returns an ended result. |
POST /api/v1/calls/{callId}/tools/{toolId} | calls:control | Approves or declines one pending invocation. |
Public keys use calls:create for these session operations and must send X-Call-Token: CALL_CONTROL_TOKEN along with Authorization and Origin. They can access only their own sessions and cannot read stored outputs or private metrics.
For a tool decision, send {"approved": true} or {"approved": false}. The path's toolId is the pending invocation ID, not the reusable tool definition ID. Approval still expires and binds to that invocation's arguments.
Errors have the shape {"error":"message"}. Validate inputs, inspect non-success responses and preserve the call ID for support. Use webhooks for durable lifecycle notifications instead of constant polling.