Guide

Agent API — Atlas for AI agents

The Agent API exposes tool execution endpoints that AI agents use to send WhatsApp messages, search knowledge, and track delivery — all scoped to the agent's granted permissions. It is the simplest path for any external AI runtime to interact with Mirai.

Two APIs, one transport layer

Atlas API

For developer integrations — OAuth apps, service accounts, webhook consumers. Full audit log, run history, and fine-grained scopes.

Base: /v1/atlas

Agent API

For AI agents — generated Atlas endpoints for manifest discovery, message sends, knowledge access, governed actions, and run history.

Base: /v1/atlas

Available tools

send_messageatlas.actions.execute

Send a governed customer message through Mirai-managed channel infrastructure.

POST /v1/atlas/messages
Body: { idempotency_key, phone_number, text, category? }
create_actionatlas.actions.execute

Create a governed Atlas action with approval, audit, and idempotency boundaries.

POST /v1/atlas/actions
Body: { type, input, idempotency_key }
list_knowledgeatlas.knowledge.read

List knowledge documents available to the active Atlas principal.

GET /v1/atlas/knowledge
list_runsatlas.actions.execute

Review run history and execution outcomes for agent workflow debugging.

GET /v1/atlas/runs
manifestatlas.actions.execute

Discover all tools available to this agent from its granted scopes.

GET /v1/atlas/tools/manifest

The 24-hour window

WhatsApp allows free-form messages only within 24 hours of a customer's last message. After that window closes, you must use a pre-approved WhatsApp template.

Window open

Send text freely. No template required.

Window closed

Include template_id and set category to match.

Delivery feedback loop

After sending a message, inspect run history or subscribe to the agent.message_delivery webhook event to be notified when the message transitions from sent → delivered → read.

GET /v1/atlas/runs

Response:
{ "ok": true, "data": { "items": [{ "status": "completed", "updated_at": "..." }] } }

status: queued | running | completed | failed

Error handling

UNAUTHORIZED

Check your Bearer token is valid and not expired.

FORBIDDEN

Your API key is missing atlas.actions.execute — ask your administrator to add it.

NOT_FOUND

The conversation_id does not exist or belongs to a different org.

VALIDATION_ERROR

Request body failed validation — check field types and required fields.

CONFLICT

Idempotency key reused with a different payload — use a new key.

Quick start

  1. 1Get an API key with atlas.actions.execute scope from the Developer Console.
  2. 2Call GET /v1/atlas/tools/manifest to see which tools are available.
  3. 3Send messages with POST /v1/atlas/messages.
  4. 4Review GET /v1/atlas/runs or subscribe to agent.message_delivery webhooks.
Build a sales AI agentFull API reference