Atlas API

Program the business-capable messaging layer.

Atlas API lets you connect WhatsApp, ingest business knowledge, launch Atlas-hosted or external AI agents, test the runtime, and send replies or proactive messages back through Mirai-managed channels with scoped credentials, idempotency, and webhook delivery. Treat preview-only paths as staged until your target environment has deployment evidence.

Make first requestView endpointsBuild a sales agent

Authentication

All requests require a Bearer token in the Authorization header:

Authorization: Bearer <your_api_key>

Tokens are scoped. The granted scopes on your key determine which endpoints you can call. Obtain keys from the Developer Console under your app or service account. Do not includeorganization_id in body or query parameters.

Base URLs

Atlas API

https://api.mirai.com/v1/atlas

For developer integrations, OAuth apps, service accounts.

Agent API

https://api.mirai.com/agent/v1

For AI agents running on Mirai — simplified auth, tool execution endpoints.

Response format

All endpoints return a consistent envelope:

Success

{ "ok": true, "data": { ... } }

Error

{ "ok": false, "error": { "code": "...", "message": "...", "retryable": false } }

Scopes

atlas.messages.send

POST /v1/atlas/messages — proactive outbound sends

atlas.channels.read

GET /v1/atlas/channels

atlas.knowledge.read

GET /v1/atlas/knowledge, GET /agent/v1/knowledge/search

atlas.knowledge.write

POST /v1/atlas/knowledge

atlas.agents.read

GET /v1/atlas/agents

atlas.agents.write

POST /v1/atlas/agents

atlas.sessions.read

GET /v1/atlas/sessions, GET /v1/atlas/sessions/:id/messages

atlas.sessions.write

POST /v1/atlas/sessions, POST /v1/atlas/sessions/:id/messages

atlas.conversations.read

GET /v1/atlas/conversations, GET /v1/atlas/context/:id

atlas.actions.execute

POST /v1/atlas/actions, all Agent API tool endpoints

atlas.events.read

GET /v1/atlas/webhooks

atlas.events.write

POST /v1/atlas/events

atlas.runs.read

GET /v1/atlas/runs

atlas.keys.write

DELETE /v1/atlas/keys/:id

Atlas API endpoints

POST/v1/atlas/messagesatlas.messages.send

Send a WhatsApp message to any phone number. Creates or reuses a customer and conversation automatically.

Request

{
  "idempotency_key": "unique-request-id",
  "phone_number": "+14155552671",
  "text": "Reminder: your appointment is tomorrow.",
  "template_id": "hello_world",
  "category": "utility"
}

Response

{ "ok": true, "data": {
  "accepted": true,
  "delivery_state": "queued",
  "conversation_id": "uuid"
}}
GET/v1/atlas/conversationsatlas.conversations.read

Returns all WhatsApp conversations for the organization.

Response

{ "ok": true, "data": { "conversations": [...] } }
GET/v1/atlas/context/:conversationIdatlas.context.read

Returns customer info, recent messages, and knowledge grounding for a conversation.

Response

{ "ok": true, "data": {
  "conversation": {...},
  "customer": {...},
  "recent_messages": [...],
  "knowledge": [...]
}}
POST/v1/atlas/eventsatlas.events.write

Feed an external event (e.g. webhook from another system) into the Atlas pipeline.

Request

{
  "idempotency_key": "evt-001",
  "channel": "whatsapp",
  "customer": { "phone_number": "+14155552671" },
  "event_type": "message.received",
  "message": { "text": "Hi" }
}

Response

{ "ok": true, "data": {
  "accepted": true,
  "conversation_id": "uuid",
  "customer_id": "uuid"
}}
POST/v1/atlas/actionsatlas.actions.execute

Reply, draft, or handoff on a conversation. Replies are sent via WhatsApp.

Request

{
  "idempotency_key": "reply-001",
  "conversation_id": "uuid",
  "action_type": "reply",
  "payload": { "text": "Thanks for reaching out!" }
}

Response

{ "ok": true, "data": {
  "accepted": true,
  "delivery_state": "queued",
  "run": {...}
}}
GET/v1/atlas/runsatlas.runs.read

Returns the audit log of all Atlas API operations for the organization.

Response

{ "ok": true, "data": { "runs": [...] } }

Agent API endpoints

The Agent API is the simplest path for AI agents running on Mirai. All endpoints require a Bearer token with atlas.actions.execute scope.

GET/agent/v1/tools/manifestatlas.actions.execute

Returns all tool definitions available to the agent, filtered by the token's granted scopes.

Response

{ "ok": true, "data": { "tools": [{ "type": "function", "function": { "name": "send_message", ... } }] } }
POST/agent/v1/tools/send_messageatlas.actions.execute

Send a WhatsApp text message within an active conversation. Requires conversation_id.

Request

{
  "conversation_id": "uuid",
  "text": "Thanks for your message!",
  "template_id": "hello_world",
  "category": "utility"
}

Response

{ "ok": true, "data": {
  "conversation_id": "uuid",
  "queued": true,
  "window_open": true,
  "outbox_id": "uuid"
}}
POST/agent/v1/tools/send_message_to_phoneatlas.actions.execute

Send to any phone number. Automatically creates or reuses a customer and WhatsApp conversation.

Request

{
  "phone_number": "+14155552671",
  "text": "Hi! Just checking in on your appointment.",
  "template_id": "hello_world",
  "category": "utility"
}

Response

{ "ok": true, "data": {
  "conversation_id": "uuid",
  "queued": true,
  "window_open": true,
  "outbox_id": "uuid",
  "phone_number": "+14155552671"
}}
GET/agent/v1/tools/messages/:providerMessageId/statusatlas.actions.execute

Check the delivery state of a sent message. status: sent | delivered | read | failed.

Response

{ "ok": true, "data": { "status": "delivered", "updated_at": "2026-04-07T00:00:00Z" } }
GET/agent/v1/knowledge/searchatlas.knowledge.read

Query the shared knowledge base for grounded answers.

Response

{ "ok": true, "data": { "results": [{ "title": "...", "content": "...", "score": 0.95 }] } }

Webhooks

Subscribe to events via POST /v1/atlas/webhooks. Available events:

atlas.event.received

Inbound event received via POST /v1/atlas/events

atlas.action.executed

Action executed via POST /v1/atlas/actions

atlas.run.updated

Run status changed

agent.message_delivery

WhatsApp delivery status changed (sent → delivered → read)

Idempotency

All mutating endpoints accept an idempotency_key. Retrying with the same key within 24 hours replays the original response without re-executing the operation.

Idempotency keys are scoped per (organization, scope, tool_name, key).

Rate limits

POST /v1/atlas/messages60 req/min per org
POST /agent/v1/tools/*120 req/min per org
POST /v1/atlas/actions30 req/min per org
Read endpoints300 req/min per org

Proactive / outbound messaging

The 24-hour conversation window is WhatsApp's session limit. While open, free-form text works. After 24 hours of silence, you must use a pre-approved WhatsApp template. Always include template_id when sending outside an active window.

Window open

Send text freely. No template needed.

Window closed

Include template_id. Set category to utility / marketing / transactional.

Build a sales AI agentWebhooks guideScopes reference