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 with403. 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.