Calls

This documents the v1 product. It is kept for integrations already running on it. If you are building something new, start with the Quickstart.

All call endpoints are workspace-scoped — send the workspace header.

These paths are named /v2/call/… but they belong to the v1 API on api.voice-agents.miraiminds.co. See hosts, not prefixes.

Initiate a call

POST /v2/call/initiate

Field	Type	Required	Description
`phoneNumber`	string	yes	E.164 recommended: `+919876543210`.
`assistant`	string	yes	Assistant `_id`.
`payload`	object	no	Values for the assistant’s variables. Shape depends on the variant — see below.
`callbackUrl`	string	no	HTTPS webhook URL.
`priority`	boolean	no	Jump the queue.
`metadata`	object	no	Arbitrary object echoed back on every webhook event. Use it to correlate.

cURL
Python
Node.js

curl -X POST https://api.voice-agents.miraiminds.co/v2/call/initiate \
  -H "x-public-key: pk_1234567890abcdef1234567890abcdef" \
  -H "x-private-key: sk_1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef" \
  -H "workspace: 6690a1b2c3d4e5f600000002" \
  -H "Content-Type: application/json" \
  -d '{
    "phoneNumber": "+919876543210",
    "assistant": "68c128a658cd7d0668bce78d",
    "callbackUrl": "https://example.com/webhooks/call-events",
    "payload": {
      "customerName": "Jane Smith",
      "orderId": "ORD-12345",
      "orderValue": 2500
    },
    "metadata": { "internalOrderId": "8842" }
  }'

import os, httpx

API = "https://api.voice-agents.miraiminds.co"
H = {
    "x-public-key": os.environ["MIRAI_PUBLIC_KEY"],
    "x-private-key": os.environ["MIRAI_PRIVATE_KEY"],
    "workspace": os.environ["MIRAI_WORKSPACE"],
}

call = httpx.post(
    f"{API}/v2/call/initiate",
    headers=H,
    json={
        "phoneNumber": "+919876543210",
        "assistant": "68c128a658cd7d0668bce78d",
        "callbackUrl": "https://example.com/webhooks/call-events",
        "payload": {"customerName": "Jane Smith", "orderId": "ORD-12345"},
        "metadata": {"internalOrderId": "8842"},
    },
    timeout=30,
).raise_for_status().json()

print(call["callId"], call["status"])  # 68f0… initiate

const API = "https://api.voice-agents.miraiminds.co";
const H = {
  "x-public-key": process.env.MIRAI_PUBLIC_KEY,
  "x-private-key": process.env.MIRAI_PRIVATE_KEY,
  workspace: process.env.MIRAI_WORKSPACE,
  "Content-Type": "application/json",
};

const call = await fetch(`${API}/v2/call/initiate`, {
  method: "POST",
  headers: H,
  body: JSON.stringify({
    phoneNumber: "+919876543210",
    assistant: "68c128a658cd7d0668bce78d",
    callbackUrl: "https://example.com/webhooks/call-events",
    payload: { customerName: "Jane Smith", orderId: "ORD-12345" },
    metadata: { internalOrderId: "8842" },
  }),
}).then((r) => r.json());

console.log(call.callId, call.status);

200 OK

{ "callId": "68f0a1b2c3d4e5f600000900", "status": "initiate" }

This endpoint returns 200, not 201, and the body is not wrapped in { status_code, message, data }. Read callId and status off the top level.

Status	Cause
`400`	Validation error
`404`	Assistant not found

`payload` by variant

custom — a flat (or nested) object whose keys match the variables you declared in variant.config.inputSchema:

{
  "payload": {
    "orderId": "ORD-12345",
    "customerName": "Jane Smith",
    "orderValue": 2500,
    "status": "pending",
    "notes": "Customer requested callback"
  }
}

abandoned_cart — the Shopify abandoned-checkout object: id, abandonedCheckoutUrl, customer, lineItems, totalPriceSet, discountCodes, shippingAddress, and so on. Pass Shopify’s payload through largely unchanged. There is no GET for a call in v1 — outcomes arrive by webhook only. If you need to read call state on demand, that is GET /v2/calls/{id} in v2.

`metadata`

Whatever you put here comes back on every event for that call:

{ "metadata": { "internalOrderId": "8842", "userId": "u_991" } }

Use it to join the webhook to your own records without keeping a callId table. v2 dropped metadata — correlate on call.id there.

Initiate a web call

POST /v2/call/web

Starts a browser-based call and returns a join token.

Field	Type	Required
`assistant`	string	yes
`systemPrompt`	string	no — overrides the assistant’s prompt for this call
`payload`	object	no
`metadata`	object	no

201 Created

{ "success": true, "token": "eyJhbGciOiJIUzI1NiIs…", "error": null }

Note the 201 here versus 200 on /v2/call/initiate.

Abort a call

POST /v2/call/abort

The call ID goes in the body, not the path.

curl -X POST https://api.voice-agents.miraiminds.co/v2/call/abort \
  -H "x-public-key: pk_1234567890abcdef1234567890abcdef" \
  -H "x-private-key: sk_1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef" \
  -H "workspace: 6690a1b2c3d4e5f600000002" \
  -H "Content-Type: application/json" \
  -d '{ "callId": "68f0a1b2c3d4e5f600000900" }'

200 OK

{ "message": "Call aborted successfully" }

A bare message — no status_code, no data. Allowed when the call has no status yet (initial queue) or is busy, failed, no-answer, rescheduled or validation-failed. Rejected with 400 when it is in-progress, completed, ended, timeout or already aborted.

Status	Cause
`400`	Already aborted, in progress, or completed
`404`	Call not found

Aborting a retryable call is how you stop the whole retry chain — otherwise retryProtocol keeps dialling.

Update a queued call’s payload

PUT /v2/call/{callId}

Replaces the payload of a call that has not been attempted yet.

curl -X PUT https://api.voice-agents.miraiminds.co/v2/call/68f0a1b2c3d4e5f600000900 \
  -H "x-public-key: pk_1234567890abcdef1234567890abcdef" \
  -H "x-private-key: sk_1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef" \
  -H "workspace: 6690a1b2c3d4e5f600000002" \
  -H "Content-Type: application/json" \
  -d '{ "payload": { "customer": { "firstName": "Jane", "phone": "+919876543210" }, "orderId": "ORD-12345" } }'

200 OK

{ "status_code": 200, "message": "Call payload updated successfully." }

The payload is replaced, not merged. Send the whole object.

Status	Cause
`400`	Validation error, or the call is already in progress / completed
`401`	Unauthorized
`404`	Call not found

Call statuses

Status	Meaning
`initiate`	Queued and being dialled.
`in-progress`	Answered; the conversation is running.
`ended`	The connection dropped.
`completed`	Recording, transcript and duration processed.
`timeout`	Exceeded `maxCallDuration`.
`failed`	Could not connect.
`validation-failed`	Pre-call validation failed, e.g. an invalid number.
`busy`	Line busy.
`no-answer`	Nobody picked up.
`skip`	Skipped, e.g. a DND number.
`rescheduled`	A callback is scheduled; the lifecycle continues.
`aborted`	Cancelled through the abort API.

Each status has a matching call.<status> webhook event.

Start

Developer guides

API v1 reference

Endpoints

Guides

Integrations

Use cases

Initiate a call

`payload` by variant

`metadata`

Initiate a web call

Abort a call

Update a queued call’s payload

Call statuses

​Initiate a call

​payload by variant

​metadata

​Initiate a web call

​Abort a call

​Update a queued call’s payload

​Call statuses

Initiate a call

`payload` by variant

`metadata`

Initiate a web call

Abort a call

Update a queued call’s payload

Call statuses