API Reference
Calls

Long-poll for live call-control events (MCP live call control)

GET
/v1/calls/{call_id}/control/events

Long-poll mailbox read for a call placed with control: "mcp" on POST /v1/calls. Returns as soon as at least one event with seq > after_seq exists, or after timeout_seconds with an empty events array and timed_out: true.

Only calls under control_mode = "mcp" are readable here — any other call 404s exactly like a missing call (calls.control_not_enabled vs calls.not_found; both 404).

Authorization

bearerAuth
AuthorizationBearer <token>

Long-lived ES256 JWT minted from the dashboard (https://app.sautikit.com/developers/api-keys). Signed by the platform keyring. Carries workspace_id and scopes claims; revoked via the platform deny-list.

In: header

Path Parameters

call_id*string

The call's Sautikit UUID, or the PBX session id the same call carries on the wire (HD_…, returned as session_id on POST /v1/calls and on every webhook). Either form addresses the same call.

Query Parameters

after_seq?integer

Return only events with seq greater than this cursor.

Formatint64
Default0
timeout_seconds?integer

Long-poll hold time; clamped to [1, 25].

Range1 <= value <= 25
Default20

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/v1/calls/string/control/events"
{  "events": [    {      "event_id": "string",      "seq": 0,      "type": "string",      "at": "2019-08-24T14:15:22Z",      "payload": {},      "response_required": true    }  ],  "next_seq": 0,  "call_status": "string",  "timed_out": true}
{  "error": {    "code": "validation.bad_request",    "message": "string",    "request_id": "string",    "details": [      "string"    ],    "resolution": "string",    "reason": "invalid_characters",    "suggested_e164": "+254727524723"  }}
{  "error": {    "code": "validation.bad_request",    "message": "string",    "request_id": "string",    "details": [      "string"    ],    "resolution": "string",    "reason": "invalid_characters",    "suggested_e164": "+254727524723"  }}
{  "error": {    "code": "validation.bad_request",    "message": "string",    "request_id": "string",    "details": [      "string"    ],    "resolution": "string",    "reason": "invalid_characters",    "suggested_e164": "+254727524723"  }}
{  "error": {    "code": "validation.bad_request",    "message": "string",    "request_id": "string",    "details": [      "string"    ],    "resolution": "string",    "reason": "invalid_characters",    "suggested_e164": "+254727524723"  }}
{  "error": {    "code": "validation.bad_request",    "message": "string",    "request_id": "string",    "details": [      "string"    ],    "resolution": "string",    "reason": "invalid_characters",    "suggested_e164": "+254727524723"  }}

Remove the supervisor DELETE

Idempotent — returns 204 whether or not a supervisor was active on the call. **Who can call this:** a signed-in workspace owner or admin, or a member holding the Supervisor licence — or an API key or OAuth token with the `calls.supervise` scope.

Submit voice actions for a control event (MCP live call control) POST

Answers a `response_required` event from `GET /v1/calls/{call_id}/control/events` with a voice-actions batch (same schema as `validate_voice_actions`). Each event can be answered exactly once.