Migrating from the v1 API to v2

v1 still runs for the integrations already on it, hosted separately at api.voice-agents.miraiminds.co. New features ship on v2 only, and we are moving v1 integrations to v2 one at a time. Your Mirai contact agrees the switch-over date with you. What you get on v2:

GET on a call. In v1, webhooks are the only way to learn a call’s status.
Campaigns, a server-side dialler with calling windows, retries, budgets, do-not-call suppression and a per-contact report. An always-on campaign is the v1 call queue.
Call analysis on the call, on its own endpoint and in a webhook, including the follow-up message template.
Your wallet balance over the API and on every call-ending webhook.
Idempotent call creation and a published rate card.
Tools before, during and after a call. Recreate each tool definition on your v2 agent; v1 tool IDs do not transfer.

Keep your v1 integration running until each part has its v2 replacement tested.

Hosts

	v1	v2
Base URL	`https://api.voice-agents.miraiminds.co`	`https://sandbox.voice.miraiminds.co`, and `https://prod.voice.miraiminds.co` once your company has gone live
Path prefix	mixed `/v1/…` and `/v2/…`	`/v2/…` throughout

The v1 host has /v2/ paths on itv1’s call endpoints really are named POST /v2/call/initiate. That /v2/ is a path segment inside the v1 product and has nothing to do with this API. Check the host to tell the two apart.

Authentication

v1	v2
`x-public-key: pk_…`	—
`x-private-key: sk_…`	`Authorization: Bearer sk_live_…`
`workspace: 6690a1b2c3d4e5f600000002`	Only to pick one of your brands, when you run them as sub-workspaces. Otherwise leave it out: the key is workspace-scoped.

v2 takes one header. The key carries the workspace, so valid credentials cannot reach the wrong workspace by accident. Create a key, and get the workspace’s webhook secret, in the console under Developers. See Start building.

The v2 API also accepts a v1 key pair, sent as the same x-public-key and x-private-key headers, once we have linked that pair to your v2 workspace. Ask your Mirai contact before you rely on it. The workspace header picks one of your sub-workspaces. A value that names neither a sub-workspace nor your own workspace is refused with 404 workspace_not_found, so leave the header out if you don’t run brands as sub-workspaces. A linked pair is a bridge for the move: v2 keys are the ones you can create, rotate and revoke in the console, so switch to one when you can.

Endpoints

v1	v2	Notes
`POST /v2/workspace/onboard/custom` and `/shopify`	The same paths	Each creates a sub-workspace for one brand, with the v1 body and response. A single-brand integration doesn’t need them: your workspace comes with your key.
`POST /v1/admin/assistant/create`	`POST /v2/agents`	”Assistant” is now “agent”.
`GET /v1/admin/assistant/get/{id}`	`GET /v2/agents/{id}`
`GET /v1/admin/assistant/list`	`GET /v2/agents`	Now cursor-paginated.
`PUT /v1/admin/assistant/update/{id}`	`PATCH /v2/agents/{id}`	`PATCH`, with partial updates.
—	`DELETE /v2/agents/{id}`	New. Soft delete.
`POST /v2/call/initiate`	`POST /v2/calls`	`200` becomes `202`. For calling hours and retries, add the number to an always-on campaign instead.
—	`GET /v2/calls/{id}`	New. v1 had no call read.
—	`GET /v2/calls`	New.
`POST /v2/call/abort` with `{callId}` in body	`POST /v2/calls/{id}/abort`	ID moves into the path.
`PUT /v2/call/{callId}` (update payload)	—	No equivalent. Set everything at create time.
`POST /v2/call/web`	`POST /v2/calls` with `channel: "web"`	Your backend creates the call and gives the page an audio link and a live event link. See Browser calls.
`GET /v1/number-pool/*`	`/v2/phone-numbers` and `/v2/telephony/*`	Different resources and IDs. Follow the inbound setup recipe; importing does not change routing until activation.
`/v1/admin/tool/api` (all methods)	`/v2/agents/{id}/tools/{name}`	Tools belong to an agent; recreate the definition instead of copying a v1 ID.
`/v1/knowledge-base/*`	`/v2/knowledge-bases`	Different resources and IDs. Add your sources again, then attach the knowledge base with the agent’s `knowledge` block.
`GET /v1/admin/voice-gallery`	—	Still v1. v2 `voice_id` values come from this same catalogue. See Voices.
—	`GET /v2/calls/{id}/transcript`	New. Turn-by-turn, as spoken.
—	`GET /v2/calls/{id}/recording`	New. `302` to a 15-minute signed URL. This is the v2 equivalent of v1’s `recordingUrl`.
—	`GET /v2/calls/{id}/analysis`	New. The post-call analysis, including the chosen message template.
`callSettings` + your own dialler	`POST /v2/campaigns` and the rest of `/v2/campaigns/*`	New. The calling window, retries and pacing that lived in v1’s assistant config now have a resource of their own.
—	`POST /v2/dnc`	New. A workspace suppression list that we check at dial time.
—	`GET /v2/wallet`	New.
—	`GET /v2/wallet/transactions`	New.

Fields

Creating an agent / assistant

v1	v2
`name`	`name`
`agent.systemPrompt`	`system_prompt`
— (first line lived in the prompt)	`first_message`
`agent.identity.voice`	`voice.voice_id`
`icpContext.language` (`"english"`)	`language` (BCP-47, `"en-IN"`)
`callSettings.maxCallDuration`	`max_duration_secs`
`variant.type` / `variant.config`	— (no variants; one shape)
`variant.config.inputSchema`	— (declare nothing; just pass `variables`)
`agent.tools`	`tools` (full definitions, not v1 tool IDs)
`preCall.apiPlan`	A `pre_call` tool
`telephony.inbound` / `telephony.outbound`	Assign `agent_id` on a v2 phone number for inbound; set the agent’s `calls_from` or the call’s `phone_number_id` for outbound. See inbound calling.
`callSettings.slots`, `concurrentCallCount`, `retryProtocol`	Settings of a campaign
`analysisPlan.summaryPlan`	`analysis.prompt`
`analysisPlan.successCriteriaPlan`	`analysis.success_criteria`
`analysisPlan.callInsightPlan`	`analysis.output_schema` (a JSON Schema of the fields to extract)
`analysisPlan.templatePlan`	`analysis.templates`

Set analysis.enabled: true to run the analysis at all. It is set per agent and reads every call of that agent that connected.

Placing a call

v1 `POST /v2/call/initiate`	v2 `POST /v2/calls`	What changes
`phoneNumber`	`to`	Must be E.164: `+`, the country code and the number, 8 to 15 digits, such as `+919876543210`. Anything else is `400 invalid_request`. v1 only recommended it.
`assistant`	`agent_id`	An `agt_…` ID.
`callbackUrl`	`webhook_url`	HTTPS. Applies to this call only. A campaign has its own `webhook_url`.
`payload`	`variables`	A flat map of strings, at most 32 keys and 512 characters per value. Flatten nested v1 payloads into keys of their own, such as `customer_first_name`, and use the same names in your prompt’s `{{placeholders}}`.
`metadata`	`metadata`	Returned on the call and on every webhook as `data.call.metadata`. At most 16 keys of 1 to 40 characters (letters, digits, `_ . : -`), string values of up to 256 characters, 4 KB in all. A nested object is refused, so flatten it. The agent never sees it.
`priority`	—	No equivalent.
`systemPrompt` (web calls)	`system_prompt`	The prompt for this call only, on phone and browser calls.
—	`first_message`	The opening line for this call only.
—	`max_duration_secs`	Overrides the agent’s cap for this call.
—	`phone_number_id` / `pool_id`	Ring from one of your own numbers or a pool.
—	`final_results`	One `call.processed` with the transcript after the call.
—	`Idempotency-Key` header	A retried request never places a second call.

v1 → v2 call request

-POST https://api.voice-agents.miraiminds.co/v2/call/initiate
-x-public-key: pk_1234…
-x-private-key: sk_abcd…
-workspace: 6690a1b2c3d4e5f600000002
+POST https://sandbox.voice.miraiminds.co/v2/calls
+Authorization: Bearer sk_live_YOUR_API_KEY
+Idempotency-Key: order-8842-confirm-1

 {
-  "phoneNumber": "+919876543210",
-  "assistant": "68c128a658cd7d0668bce78d",
-  "callbackUrl": "https://example.com/mirai/webhook",
-  "payload": { "customer": { "firstName": "Rahul" }, "orderId": "8842" },
-  "metadata": { "internalOrderId": "8842" }
+  "to": "+919876543210",
+  "agent_id": "agt_01JZQ8F3K7M2N5P9R4T6V8W0XZ",
+  "webhook_url": "https://example.com/mirai/webhook",
+  "variables": { "customer_first_name": "Rahul", "order_id": "8842" },
+  "metadata": { "internal_order_id": "8842" }
 }

v1 → v2 response

-200 OK
-{ "callId": "68f0…", "status": "initiate" }
+202 Accepted
+{ "id": "call_01JZQ9B4M8N3P6R2S5T7V9W1YA", "status": "queued" }

Retries, calling hours and concurrency

In v1, every call you placed joined a queue on the assistant, which applied its calling slots, its concurrency limit and its retry protocol. POST /v2/calls places one attempt now: no calling window, no redial. To keep v1’s behaviour, create one campaign for the agent with "always_on": true, start it, and add each number to it with POST /v2/campaigns/{id}/contacts where you used to call POST /v2/call/initiate. The campaign calls each number inside its window, within its concurrency, and retries the ones that did not connect. It stays open after the list is done. See always-on campaigns for a worked example.

v1 assistant `callSettings`	v2 campaign
`slots: [{ startTime, endTime }]`	`slots: [{ start, end }]`, plus `timezone` and `start_date` / `end_date`
`concurrentCallCount`	`max_concurrent` (1 to 50)
`retryProtocol.maxAttemptsNoPickup`	`retry_count` (0 to 5). Retries `no_answer`, `busy` and `failed`.
`retryProtocol.reAttemptPeriod`	`re_attempt_period_secs` (60 to 86,400)
`retryProtocol.maxAttemptsLowEngagement`	No equivalent. Calls that reached someone (`completed`, `voicemail`, `timeout`) are never redialled.
`retryProtocol.maxRescheduleCount`	The agent’s callback tool
a call’s `payload` and `metadata`	the contact’s `variables` and `metadata`, with the same limits as a call

Two differences to plan for. A campaign holds each phone number once, so adding a number already in it is counted as a duplicate and not called again. And an add to a campaign that has been stopped, or whose end_date has passed, gets 409 conflict. Any 200 means the numbers are in line to be called.

Statuses

v1’s status vocabulary is hyphenated and mixes phases with outcomes. v2 uses snake_case and separates status from ended_reason.

v1 status	v2 `status`
`initiate`	`queued`, then `dialing`
`in-progress`	`in_progress`
`ended`, `completed`	`completed`
`no-answer`	`no_answer`
`busy`	`busy`
`failed`, `validation-failed`	`failed` (a bad `to` is a `400` at create time in v2)
`timeout`	`timeout`
`aborted`	`aborted`
`skip`	contact status `suppressed` inside a campaign; nothing for single calls
`rescheduled`	contact status `pending` again, until `retry_count` runs out and it becomes `exhausted`
—	`voicemail` (new)

Webhooks

	v1	v2
Signature header	`x-signature` (bare hex) + `x-public-key`	`X-Mirai-Signature: t=…,v1=…`
Signed material	raw body	`"<t>.<raw_body>"`
Secret	organization private key	the workspace’s `whsec_…`
Replay protection	none	reject deliveries more than 300 seconds old
Event ID	none	`id: evt_<ulid>`, dedupe on it
Envelope	`{ metadata, event: { type, data } }`	`{ id, type, created_at, data }`
Retries	—	six attempts over about 36 minutes, then a dead-letter queue we can replay

Point a new route at the v2 scheme. The two signatures are not interchangeable, and you need both routes while calls run on both versions. Signature verification has the code and a test vector.

Events

v1 event	v2 event
`call.initiate`	`call.queued`, which is opt-in: ask your Mirai contact
`call.in-progress`	`call.started`
`call.ended`	No separate event. The terminal event follows the hangup.
`call.completed`	`call.completed`
`call.timeout`	`call.failed` with `data.call.status: "timeout"`
`call.failed`, `call.busy`, `call.no-answer`	`call.failed` with `data.call.status` `failed`, `busy` or `no_answer`
`call.validation-failed`	No event: `POST /v2/calls` answers `400 invalid_request`
`call.skip`	No event: the campaign contact’s status becomes `suppressed`
`call.rescheduled`	No event: the campaign contact goes back to `pending` for its retry
`call.aborted`	`call.aborted`
—	`call.voicemail` (new)
`end-of-call`	`call.processed`, with the analysis at `data.call.analysis`
`call.lifecycle-ended`	For a single call, the terminal event is the last word. In a campaign, read the contact’s status: `exhausted` means its retries ran out.
`action`	No event. Extract the fields with `analysis.output_schema`, choose a message with `analysis.templates`, or act from a post-call tool.

Exactly one terminal event fires per call: call.completed, call.voicemail, call.failed or call.aborted. Campaigns add campaign.* events. See event types.

Fields

v1	v2
`metadata` (top level)	`data.call.metadata`
`event.type`	`type`
`event.data.call.id`	`data.call.id` (`call_…`)
`event.data.call.status`	`data.call.status` (see Statuses)
`startedAt` / `endedAt`	`data.call.started_at` / `data.call.ended_at`
`durationSeconds`	`data.call.duration_secs`
`recordingUrl`	`GET /v2/calls/{id}/recording`, an authenticated request that redirects to a 15-minute signed URL
`detailUrl`	—
`analysis.summary`	`data.call.analysis.summary` on `call.processed`
`analysis.success`	`data.call.analysis.success`
`analysis.insights`	`data.call.analysis.data`, in the shape of your `output_schema`
`analysis.insights.template`	`data.call.analysis.template`. See below.
`analysis.requiredActions`	—
`credits.used`	`data.call.cost.amount_inr`, in rupees
`credits.available`	`data.wallet.balance_inr` on the terminal event, in rupees. See wallet balance.
`report.reAttemptCount`	`attempts` on the campaign contact

v1 → v2 webhook body

 {
-  "metadata": { "internalOrderId": "8842" },
-  "event": {
-    "type": "call.completed",
-    "data": {
-      "call": {
-        "id": "68f0…",
-        "status": "completed",
-        "durationSeconds": 96,
-        "recordingUrl": "https://…"
-      },
-      "credits": { "used": 1.5, "available": 98.5 }
-    }
-  }
+  "id": "evt_01JZQ9C5N9P4R7S3T6V8W2X4YB",
+  "type": "call.completed",
+  "created_at": "2026-07-26T09:16:38Z",
+  "data": {
+    "call": {
+      "id": "call_01JZQ9B4M8N3P6R2S5T7V9W1YA",
+      "status": "completed",
+      "ended_reason": "assistant-ended-call",
+      "duration_secs": 96,
+      "cost": { "amount_inr": 5, "per_min_inr": 3, "billing_block_secs": 10 },
+      "metadata": { "internal_order_id": "8842" }
+    },
+    "wallet": { "balance_inr": 18432.5 }
+  }
 }

Money is in rupees on v2, not credits: cost.amount_inr is what this call cost and wallet.balance_inr is what is left after it. The balance is a snapshot taken when the call was billed, and it is left out when we could not read it. The analysis moves from end-of-call to call.processed, which follows the terminal event once the analysis and any post-call tools have finished. Turn on final_results to get the transcript in the same event.

Message templates after the call

If your v1 assistant chose a message template after each call (analysisPlan.templatePlan, with the result at analysis.insights.template), use analysis.templates on the v2 agent. v1 sent {"assistantId": "<id>"} to your URL and read the Data list from the answer. A fetch can send exactly the same request, so your template endpoint keeps working unchanged:

{
  "analysis": {
    "enabled": true,
    "templates": {
      "instructions": "Pick the WhatsApp message to send after this call. Choose none if the customer declined.",
      "fetch": {
        "method": "POST",
        "url": "https://api.example.com/templates",
        "body": { "assistantId": "68c128a658cd7d0668bce78d" },
        "items_path": "Data"
      }
    }
  }
}

v1 called your endpoint without credentials. On v2 you can add a header with a workspace secret, such as "headers": { "Authorization": "Bearer {{ secrets.templates_key }}" }, and check it on your side.

v1 `analysis.insights.template`	v2 `analysis.template`
`name`, or `NONE` when nothing fits	`status: "selected"` with `name`, or `status: "none"`
`language`	`language`
`variables` with `""` for anything unknown	`variables` holds only filled slots. Unknown slots are listed in `missing`.
Failures dropped silently	`status: "failed"` with `error.code`. The rest of the analysis still arrives.
—	`reason`, one sentence on the choice
In `end-of-call`	In `call.processed`, on the call and at `GET /v2/calls/{id}/analysis`

Before you send a template, check that missing is empty, or fill those slots yourself.

Errors

v1	v2
`{ "code": 400, "message": "…" }`	`{ "error": { "code": "invalid_request", "message": "…" } }`
`{ "status_code": 200, "message": "…", "data": {…} }` on success	the resource object directly
`code` is a number	`error.code` is a `snake_case` string; the number is the HTTP status

v1’s success responses wrap the payload in { status_code, message, data }. v2 returns the resource itself. See the error reference.

A migration plan

Get a v2 key and the webhook secret from Developers in the console. Keep your v1 credentials, because you will run both for a while.
Recreate your assistants as agents. Move the opening line out of systemPrompt into first_message, rename your payload keys to flat variables keys your prompt references, and move analysisPlan to analysis, templates included.
Point a new webhook route at the v2 signature scheme and the v2 event names. Do not modify the v1 route.
Decide how calls are placed. For calls that need calling hours and retries, create an always-on campaign per agent and add numbers to it. For a call that must ring now, use POST /v2/calls with an Idempotency-Key.
Switch one low-volume flow to v2 and compare its outcomes with the same flow on v1 for a day.
Recreate and test your tools on the v2 agent, then move the remaining calls. Add your documents and website to a knowledge base and attach it to the v2 agent before moving assistants that use the v1 knowledge base.

Start here

Build

Prompting

Speech API

Text to speech

Speech to text

Language model

Money

Reference

Migrating from the v1 API to v2

Hosts

Authentication

Endpoints

Fields

Creating an agent / assistant

Placing a call

Retries, calling hours and concurrency

Statuses

Webhooks

Events

Fields

Message templates after the call

Errors

A migration plan

​Hosts

​Authentication

​Endpoints

​Fields

​Creating an agent / assistant

​Placing a call

​Retries, calling hours and concurrency

​Statuses

​Webhooks

​Events

​Fields

​Message templates after the call

​Errors

​A migration plan

Hosts

Authentication

Endpoints

Fields

Creating an agent / assistant

Placing a call

Retries, calling hours and concurrency

Statuses

Webhooks

Events

Fields

Message templates after the call

Errors

A migration plan