v1 API (stable)

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 v1

v1’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.

Contact sneh@miraiminds.co for credentials.

Danger

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