Base URLs
The routes are the same on both. The console’s Developers page shows the
base URL for your key; a sandbox key sent to the production URL is refused.
Authentication
Every request carries your workspace’s secret key as a bearer token:sk_live_ followed by 32 hex characters, and it belongs to one
workspace. Create, rotate and revoke keys in the console under Developers.
The key is shown once; we keep only its hash, so a lost key is rotated, not
recovered.
A workspace that runs brands as sub-workspaces uses the
same key for all of them. Add Mirai-Workspace: <sub-workspace id or your external_id> to act inside one brand; X-Workspace and Workspace are read the
same way. Without the header, a request acts on your own workspace.
The fix for each money and access error is in
Errors. To move to production, go live.
Keep the key on your server. A browser or a mobile app never gets it: for
browser calls and speech streams
your server hands the page short-lived links instead.
Trying requests from these pages
Each endpoint page has a Try it panel. Paste your key into theAuthorization field, pick the server, and send. These are real requests
against your workspace: Place a call rings a real phone and uses wallet
credit, and anything you create stays in your workspace. Use a sandbox key
while you explore.
Requests and responses
- JSON in and out. Send
Content-Type: application/jsonwith every body. Responses are JSON, including errors. The few exceptions (audio, CSV reports, file uploads) say so on their page. - IDs are opaque strings with a type prefix:
agt_for agents,call_for calls,cmp_for campaigns. Store them as they are. - Timestamps are RFC 3339 in UTC:
2026-10-18T09:14:02Z. - Money is in rupees (
amount_inr,balance_inr), except campaign budgets, which are integer paise. - Phone numbers are E.164 with the leading
+:+919876543210.
Errors
Errors carry a stable code you can branch on, and a message for your logs:{"error": "invalid_tools" | "invalid_flow", "details": [...]} with one
entry per problem. Every code, its status and whether to retry are listed in
Errors.
Pagination
List endpoints takelimit and cursor and answer with the same envelope:
next_cursor back as cursor for the next page, and stop when has_more
is false. Lists are newest first.
Idempotency
POST /v2/calls, POST /v2/agents, POST /v2/transcriptions and live call
controls take an Idempotency-Key header. The same key within 24 hours returns
the first answer and creates nothing new, so a retry never places a second
call. Build the key from your own record, such as order-8842-reminder-1,
rather than a fresh random value on each attempt.
Webhooks and live events
Calls report their progress to yourwebhook_url as signed events. The event
types, payloads and signature check are in Webhooks.
Every call also has a live event stream with the agent’s state and each turn
while it runs: phone calls you place, campaign and inbound calls, browser calls
and realtime sessions. Creating a call returns events_url, which a browser can
open without your key, and your key opens the stream of any call in your
workspace. See Live events.