v1 API (stable)

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

v1 is the API that runs today’s production integrations. It is stable and supported — nothing here is being removed.

https://api.voice-agents.miraiminds.co

Environment	Base URL
Production	`https://api.voice-agents.miraiminds.co`
Staging	`https://api.stage.voice-agent.miraiminds.co`

v1 or v2?v1 has the broad surface: inbound calls, phone-number purchase, knowledge base/RAG, API tools, campaigns, post-call analysis. v2 has the clean one: one auth header, GET on calls, a wallet API and idempotency — but only outbound calls and agents. They address the same workspace and can run side by side. See the mapping table.

Hosts, not prefixes

The /v2/ paths on this host are v1v1’s call endpoints are named POST /v2/call/initiate, POST /v2/call/abort and so on. That /v2/ is a path segment inside this API, unrelated to the v2 API. What distinguishes the two APIs is the host:

API	Host
v1 (this one)	`api.voice-agents.miraiminds.co`
v2	`api.voice.miraiminds.co`

Workspaces

Onboard, archive, health. Reference.

Assistants

The v1 equivalent of an agent. Reference.

Calls

Initiate, abort, update payload, web calls. Reference.

Webhooks

15 event types and the x-signature scheme. Reference.

Authentication

Every request except GET /health carries two key headers. Workspace-scoped endpoints add a third.

Header	Required on	Value
`x-public-key`	everything	`pk_` + 32 hex
`x-private-key`	everything	`sk_` + 64 hex
`workspace`	workspace-scoped endpoints	the workspace `_id` returned at onboarding

curl https://api.voice-agents.miraiminds.co/v1/admin/assistant/list \
  -H "x-public-key: pk_1234567890abcdef1234567890abcdef" \
  -H "x-private-key: sk_1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef" \
  -H "workspace: 6690a1b2c3d4e5f600000002"

A few admin endpoints (organization archive/unarchive) additionally require an admin or organization_admin role, carried as a JWT bearer token. v1 pairs are issued with your account. For a new v2 key you do not need to ask anyone — create it in the console under Developers, and see Migrating from v1.

The x-private-key is a secret and the webhook signing key. Never put it in a browser, a mobile app, or a repo.

Entity hierarchy

Organization
└── Workspace                (holds assistants + telephony numbers)
    └── Assistant
        ├── Telephony        (inbound + outbound phone numbers)
        ├── Knowledge Base   (documents + FAQ for RAG)
        └── Analysis Plan    (post-call AI evaluation)

IDs are 24-character Mongo ObjectIds: 6690a1b2c3d4e5f600000002.

Response envelopes

v1 wraps most successful responses:

{
  "status_code": 200,
  "message": "Assistants fetched successfully.",
  "data": { }
}

Errors use a flat shape where code is a number:

{ "code": 400, "message": "Validation error" }

Known inconsistencies — these are contract, not bugs to work around

POST /v2/call/initiate returns 200, while POST /v2/call/web, POST /v1/number-pool/purchase, POST /v1/admin/tool/api and POST /v1/knowledge-base/upload/start return 201.
POST /v2/call/abort returns a bare { "message": "…" } with no status_code wrapper. PUT /v2/call/{callId} returns { "status_code", "message" } with no data.
Some error bodies use code, some use status_code. Read the HTTP status first and the body second.

Handle these explicitly rather than assuming a uniform envelope. v2 is uniform.

Status codes

Code	Meaning
`200`	Success
`201`	Created (see the list above for which endpoints)
`400`	Validation error, or the resource is archived
`401`	Missing or invalid key headers
`402`	Insufficient credit balance
`403`	Insufficient role, or the operation is not allowed for this org type
`404`	Not found in this workspace
`409`	Already exists / already released / in use
`429`	Rate limit exceeded
`500`	Internal error

Health

GET /health

No authentication.

curl https://api.voice-agents.miraiminds.co/health

{
  "status_code": 200,
  "message": "Platform is operational.",
  "data": { "underMaintenance": false, "status": "healthy" }
}

Check data.underMaintenance before starting a large campaign.

Quickstart

1 — Create a workspace

POST /v2/workspace/onboard/custom. A default telephony number is assigned automatically in production. How

2 — Create an assistant

POST /v1/admin/assistant/create with variant.type: custom and your agent.systemPrompt. How

3 — Make a call

POST /v2/call/initiate with callbackUrl for webhooks. How

Start

Developer guides

API v1 reference

Endpoints

Guides

Integrations

Use cases

Hosts, not prefixes

Workspaces

Assistants

Calls

Webhooks

Authentication

Entity hierarchy

Response envelopes

Status codes

Health

Quickstart

1 — Create a workspace

2 — Create an assistant

3 — Make a call

​Hosts, not prefixes

Workspaces

Assistants

Calls

Webhooks

​Authentication

​Entity hierarchy

​Response envelopes

​Status codes

​Health

​Quickstart

1 — Create a workspace

2 — Create an assistant

3 — Make a call

Hosts, not prefixes

Authentication

Entity hierarchy

Response envelopes

Status codes

Health

Quickstart