API overview - Voice Agents

Two resources — agents and calls — one auth header, and the same error envelope everywhere.

https://api.voice.miraiminds.co

Quickstart

Key → agent → call → webhook in five minutes. Start here.

Agents

The reusable configuration a call runs. Reference.

Calls

Place, inspect and abort outbound calls. Reference.

Webhooks

Signed lifecycle events. Guide.

Authentication

Every request carries one header:

Authorization: Bearer sk_live_YOUR_API_KEY

A secret key is sk_live_ followed by 32 hex characters. It is scoped to one workspace and carries your default tier. Create, rotate and revoke keys yourself in the console under Developers. We store only the SHA-256 of your key, so a lost key cannot be recovered — it is rotated. Never ship a secret key to a browser or a mobile app.

Situation	Status	`error.code`
Header missing or key unknown	`401`	`unauthorized`
Key revoked	`403`	`forbidden`

Conventions

JSON only. Send Content-Type: application/json on every request with a body. Responses are always JSON, including errors. IDs are server-minted and prefixed by resource type. Treat them as opaque strings — do not parse them.

Resource	Format	Example
Agent	`agt_<ulid>`	`agt_01JZQ8F3K7M2N5P9R4T6V8W0XZ`
Call	`call_<ulid>`	`call_01JZQ9B4M8N3P6R2S5T7V9W1YA`
Webhook event	`evt_<ulid>`	`evt_01JZQ9C5N9P4R7S3T6V8W2X4YB`

Errors always use one envelope. See the full error reference.

{
  "error": {
    "code": "insufficient_balance",
    "message": "wallet balance 0.40 INR is below the minimum for one minute at t1"
  }
}

Timestamps are RFC 3339 in UTC: 2026-07-26T09:14:02Z. Money is INR. amount_inr and per_min_inr are numbers, not strings. Phone numbers are E.164 with the leading +: +919876543210.

Pagination

List endpoints take limit and cursor and return a cursor-paginated envelope.

curl "https://api.voice.miraiminds.co/v2/calls?limit=50&cursor=call_01JZQ9B4M8N3P6R2S5T7V9W1YA" \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"

{
  "data": [ { "id": "call_01JZQ9B4M8N3P6R2S5T7V9W1YA", "…": "…" } ],
  "has_more": true,
  "next_cursor": "call_01JZQ9B4M8N3P6R2S5T7V9W1YB"
}

Pass next_cursor back as cursor to get the following page. Stop when has_more is false. Default limit is 20, maximum 100.

Idempotency

POST /v2/calls accepts an Idempotency-Key header. Reuse the key and you get the original response replayed instead of a second phone call. Keys are held for 24 hours.

-H "Idempotency-Key: order-8842-reminder-1"

Use something derived from your own domain object (an order ID, a job ID) rather than a random UUID per attempt — the point is that your retry produces the same key. See Calls.

Not built yet

Outbound calling is what this API does. These are known gaps, listed so you find out here rather than halfway through a build:

Inbound calls. Outbound only.
Buying phone numbers. We provide the line.
Knowledge base / RAG and function calling during a call.
Self-serve wallet top-up — see the roadmap.
OAuth or user-scoped tokens. Secret keys only.

If one of these is in your way, say so — several are on the roadmap and the order is not fixed.

Quickstart

Agents

Calls

Webhooks

​Authentication

​Conventions

​Pagination

​Idempotency

​Not built yet

Authentication

Conventions

Pagination

Idempotency

Not built yet