Skip to content

REST API Reference

Most integrations should use MCP — it's the supported, higher-level surface, and its tools carry their own schemas. This page is for when you want to script the console's own HTTP API directly: dashboards, provisioning automation, a custom UI.

MCP is the contract; this is the console's own API

The /api/* routes back the web console and evolve with it. MCP tools are the stable, documented integration surface. Prefer MCP unless you specifically need something it doesn't expose.

Auth

Every /api/* route (except the public ones below) needs an identity:

  • Cookie — a signed session from console login, for browser clients.
  • Bearer key — Authorization: Bearer <key>, for machine clients. A key is device-bound: it authenticates as its owner but is scoped to its one device, and it reaches only the routes an agent needs (device status, calls, call history and recordings, listing assistants). Account, key, provider, assistant-editing and payment routes need a signed-in person and answer a key with 403. Per-key rate limits apply — see Rate limits.

Public, no auth: GET /health, GET /metrics, GET /api/auth/methods, the OAuth start/callback pair, and POST /api/auth/internal-access/exchange (invitation-code sign-in).

Errors are JSON with a stable error code — route on the code, not the prose:

Status error Meaning
400 (varies) Malformed input.
401 login_required No/!valid identity.
402 insufficient_credits The account can't fund the call.
403 human_session_required · insufficient_scope A device key (or an app connection) called a route outside what it may do; sign in as a person, or connect with the permission you need.
404 not_found Missing — or present but not yours (see Security).
429 rate_limited Per-key bucket is dry.

Auth & account

Method Path Purpose
GET /api/auth/methods Available sign-in methods.
GET/POST /api/auth/oauth/{method_id}/start · /callback OAuth handshake for one method.
POST /api/auth/internal-access/exchange Exchange an invitation code: {credential, purpose} → a signed cookie (web) or a bridge device token (bridge).
POST /api/auth/logout Clear the session cookie.
GET /api/auth/whoami The current identity.
GET /api/auth/cli/start Begin the device-login flow for a command-line client.
GET /api/account Account summary.
GET /api/usage · /api/me/metrics Usage / metrics for the signed-in account.

Devices

Method Path Purpose
GET /me/devices The caller's bound devices (alias-first).
PATCH /me/devices/{device_id} Rename — alias only; binding and URLs are unaffected.
POST /api/devices/provision Register a device (what flashing calls under the hood).
GET /api/devices/{device_id} One device's record.
GET /api/devices/{device_id}/status Live status: online, Bluetooth, call state, link RTT/age.
GET /api/devices/{device_id}/metrics · /metrics/range Device telemetry, point or windowed.
GET /api/devices/{device_id}/bt-events Recent Bluetooth link events.
GET/POST /api/devices/{device_id}/assistant Read / set the device's standing assistant.
GET /api/devices/{device_id}/credits Per-device spend.
GET /api/client_queue?device_id=… Live bridge/connection stats for a device.
GET /api/bridge/ws-endpoint The WebSocket endpoint a bridge should dial.

Calls

Method Path Purpose
GET /api/calls/history Recent calls (the History list).
POST /api/calls/history/delete Delete your finished calls and their saved content; device keys restrict deletion to their bound device.
GET /api/calls/{call_id} One call's record.
GET /api/calls/{call_id}/result Outcome, summary, transcript, extracted fields.
GET /api/calls/{call_id}/metrics Per-call metrics blob.
GET /api/calls/{call_id}/replay Replay data — transcript synced to the recording.
GET /api/events?device_id=… Long-poll feed of the device's current call (cursor, types, wait up to 30 s) — what MCP get_call_events relays.
GET /recordings/{call_id}/caller.wav · /ai.wav The call's two recorded tracks (the other party, the AI). /replay lists their URLs.

Placing, answering and steering calls are REST routes too — they are what the MCP tools (place_call, answer_call, steer_call, …) relay to — but their request shapes are not documented here. Use MCP for them.

Deleting call history

Send {"call_ids": ["call_id_1", "call_id_2"]} to POST /api/calls/history/delete with your signed-in account cookie or a valid device-bound Bearer key. A request accepts 1–100 explicit call IDs. Only the call's immutable account owner can delete it, after it has ended. Account sessions can delete their own calls across devices; device keys can delete only their own account's calls on the key's bound device. Reading account-wide history does not grant account-wide deletion. For agents, use MCP delete_calls(call_ids) on /mcp.

The response separates committed logical deletions from failed requests:

{
  "deleted": ["call_id_1"],
  "failed": [{"call_id": "call_id_2", "user_message": "This call could not be deleted. Refresh call history and retry."}]
}

A deleted ID means the logical deletion was committed. All new public reads (including MCP results and old recording links) exclude the call. Conversation content, recordings and saved files are removed afterward. Credits already used, billing transactions and usage totals remain unchanged. Downloaded copies stay on your device.

Assistants & providers

Method Path Purpose
GET/POST /api/assistants List / create.
GET/PUT/DELETE /api/assistants/{id} Read / partial edit (edits are versioned) / delete your assistant.
POST /api/assistants/{id}/duplicate Create an independent copy.
GET /api/assistants/{id}/versions · /versions/{v} · POST /versions/{v}/restore Version history and restore.
POST /api/assistants/assist · /validate · /{id}/ai-check Authoring aids: draft, validate, AI review.
POST /api/assistants/{id}/test-call · /trial-device Fire a test call / attach a browser trial device.
GET /api/assistants/{id}/stats Per-assistant call stats.
GET /api/protocols · /protocols/{protocol} Provider roster; one protocol's model/voice lists.
GET /api/protocols/{protocol}/voice-preview?voice=… Sample a voice.
GET/POST /api/me/providers List / add your own vendor credentials.
GET/PATCH/DELETE /api/me/providers/{id} Manage one.
POST /api/me/providers/{id}/validate Check a credential works.

Credits & keys

Method Path Purpose
GET /api/credits Balance and ledger.
POST /api/credits/topup Start a Stripe Checkout for the credit package currently offered in Account; credits are added after payment.
GET /api/keys Your API keys (never the secrets).
POST /api/keys Mint a device-bound key {device_id, name, rate_per_min?} — the secret is returned once.
DELETE /api/keys/{key_id} Revoke a key, effective immediately.

Rate limits

Machine (Bearer-key) requests are rate-limited per key. Set a key's ceiling with rate_per_min when you mint it via POST /api/keys; omit it for no limit. The bucket holds a full minute's burst and refills at rate_per_min / 60 tokens per second, so a dry bucket returns 429 rate_limited — a code an AI client can back off on rather than a wall.

402 insufficient_credits is a balance error, not a rate limit. Check your balance and the applicable rates before retrying.