{ "openapi": "3.1.0", "info": { "title": "Mirai Atlas API", "version": "0.1.0-preview", "description": "Generated contract registry for Atlas API. Developer Console and public Atlas launch endpoints are live from the shared contract registry." }, "servers": [ { "url": "https://api.usemirai.app", "description": "Public Atlas API" }, { "url": "https://app.usemirai.app", "description": "Authenticated Mirai Developer Console" } ], "components": { "securitySchemes": { "DeveloperConsoleBearer": { "type": "http", "scheme": "bearer", "description": "Authenticated Mirai operator session" }, "AtlasBearer": { "type": "http", "scheme": "bearer", "description": "OAuth or service-account bearer token" } } }, "paths": { "/operator/developers/overview": { "get": { "tags": [ "Developer Console" ], "summary": "Read Developer Console counts and granted permissions", "description": "Returns the owner-scoped Developer Console summary for the current Mirai organization.", "operationId": "developer_console_overview_get", "security": [ { "DeveloperConsoleBearer": [] } ], "x-mirai-visibility": "developer_console", "x-mirai-status": "implemented", "x-required-permissions": [ "developer_console.read" ], "x-required-scopes": [], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "ok": true, "data": { "counts": { "apps": 1, "service_accounts": 2, "webhooks": 1, "audit_events": 12 }, "permissions": { "developer_console": { "read": true, "manage": true } } } } } } } } } }, "/operator/developers/apps": { "get": { "tags": [ "Developer Console" ], "summary": "List org-owned Atlas apps", "description": "Lists Atlas apps and registered redirect URIs for the active workspace.", "operationId": "developer_console_apps_list", "security": [ { "DeveloperConsoleBearer": [] } ], "x-mirai-visibility": "developer_console", "x-mirai-status": "implemented", "x-required-permissions": [ "atlas_api.apps.read" ], "x-required-scopes": [], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "ok": true, "data": { "apps": [ { "id": "app_123", "client_id": "atl_client_abc", "name": "ABC Sales Agent", "runtime_mode": "external_agent", "redirect_uris": [ { "id": "redir_123", "redirect_uri": "https://abc.example.com/callback" } ] } ] } } } } } } }, "post": { "tags": [ "Developer Console" ], "summary": "Create an org-owned Atlas app", "description": "Creates a Developer Console app asset owned by the current organization.", "operationId": "developer_console_apps_create", "security": [ { "DeveloperConsoleBearer": [] } ], "x-mirai-visibility": "developer_console", "x-mirai-status": "implemented", "x-required-permissions": [ "atlas_api.apps.write" ], "x-required-scopes": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "name": "ABC Sales Agent", "description": "Outbound and inbound sales-assistant integration", "runtime_mode": "external_agent" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "ok": true, "data": { "app": { "id": "app_123", "client_id": "atl_client_abc", "name": "ABC Sales Agent", "runtime_mode": "external_agent" } } } } } } } } }, "/operator/developers/apps/{appId}/redirect-uris": { "post": { "tags": [ "Developer Console" ], "summary": "Register an OAuth redirect URI", "description": "Adds a redirect URI to an existing org-owned Atlas app.", "operationId": "developer_console_apps_redirect_uris_create", "security": [ { "DeveloperConsoleBearer": [] } ], "x-mirai-visibility": "developer_console", "x-mirai-status": "implemented", "x-required-permissions": [ "atlas_api.oauth.manage" ], "x-required-scopes": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "redirect_uri": "https://abc.example.com/callback" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "ok": true, "data": { "redirect_uri": { "id": "redir_123", "redirect_uri": "https://abc.example.com/callback" } } } } } } } } }, "/operator/developers/apps/{appId}/grants": { "post": { "tags": [ "Developer Console" ], "summary": "Mint an app access grant", "description": "Creates an org-owned app bearer token for Atlas API access and returns the plaintext secret once.", "operationId": "developer_console_apps_grants_create", "security": [ { "DeveloperConsoleBearer": [] } ], "x-mirai-visibility": "developer_console", "x-mirai-status": "implemented", "x-required-permissions": [ "atlas_api.oauth.manage" ], "x-required-scopes": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "granted_scopes": [ "atlas.events.read", "atlas.context.read", "atlas.actions.execute" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "ok": true, "data": { "grant": { "id": "grant_123", "grant_status": "active", "granted_scopes": [ "atlas.events.read", "atlas.context.read", "atlas.actions.execute" ], "token_prefix": "mirai_atlas_abcd", "secret": "mirai_atlas_secret" } } } } } } } } }, "/operator/developers/service-accounts": { "get": { "tags": [ "Developer Console" ], "summary": "List service accounts and key metadata", "description": "Lists org-owned service accounts together with key prefixes and granted scope metadata.", "operationId": "developer_console_service_accounts_list", "security": [ { "DeveloperConsoleBearer": [] } ], "x-mirai-visibility": "developer_console", "x-mirai-status": "implemented", "x-required-permissions": [ "atlas_api.service_accounts.manage" ], "x-required-scopes": [], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "ok": true, "data": { "service_accounts": [ { "id": "sa_123", "external_id": "atl_sa_abc", "name": "ABC External Agent", "keys": [ { "id": "key_123", "key_prefix": "mirai_atlas_abcd", "granted_scopes": [ "atlas.events.read", "atlas.actions.execute" ] } ] } ] } } } } } } }, "post": { "tags": [ "Developer Console" ], "summary": "Create a service account", "description": "Creates an org-owned machine principal for Atlas API access.", "operationId": "developer_console_service_accounts_create", "security": [ { "DeveloperConsoleBearer": [] } ], "x-mirai-visibility": "developer_console", "x-mirai-status": "implemented", "x-required-permissions": [ "atlas_api.service_accounts.manage" ], "x-required-scopes": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "name": "ABC External Agent", "description": "Machine identity for sales-agent runtime", "runtime_mode": "external_agent" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "ok": true, "data": { "service_account": { "id": "sa_123", "external_id": "atl_sa_abc", "name": "ABC External Agent" } } } } } } } } }, "/operator/developers/service-accounts/{serviceAccountId}/keys": { "post": { "tags": [ "Developer Console" ], "summary": "Mint a service-account key", "description": "Creates a new scoped key and returns the plaintext secret exactly once.", "operationId": "developer_console_service_account_keys_create", "security": [ { "DeveloperConsoleBearer": [] } ], "x-mirai-visibility": "developer_console", "x-mirai-status": "implemented", "x-required-permissions": [ "atlas_api.keys.manage" ], "x-required-scopes": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "granted_scopes": [ "atlas.events.read", "atlas.context.read", "atlas.actions.execute" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "ok": true, "data": { "key": { "id": "key_123", "key_prefix": "mirai_atlas_abcd", "granted_scopes": [ "atlas.events.read", "atlas.context.read", "atlas.actions.execute" ], "secret": "mirai_atlas_secret" } } } } } } } } }, "/operator/developers/webhooks": { "get": { "tags": [ "Developer Console" ], "summary": "List webhook endpoints", "description": "Lists outbound webhook endpoints and subscribed event families.", "operationId": "developer_console_webhooks_list", "security": [ { "DeveloperConsoleBearer": [] } ], "x-mirai-visibility": "developer_console", "x-mirai-status": "implemented", "x-required-permissions": [ "atlas_api.webhooks.manage" ], "x-required-scopes": [], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "ok": true, "data": { "webhook_endpoints": [ { "id": "webhook_123", "endpoint_url": "https://abc.example.com/atlas/webhooks", "subscribed_events": [ "atlas.event.received", "atlas.run.updated" ] } ] } } } } } } }, "post": { "tags": [ "Developer Console" ], "summary": "Create a webhook endpoint", "description": "Registers an outbound webhook endpoint and returns the signing secret once.", "operationId": "developer_console_webhooks_create", "security": [ { "DeveloperConsoleBearer": [] } ], "x-mirai-visibility": "developer_console", "x-mirai-status": "implemented", "x-required-permissions": [ "atlas_api.webhooks.manage" ], "x-required-scopes": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "service_account_id": "sa_123", "endpoint_url": "https://abc.example.com/atlas/webhooks", "subscribed_events": [ "atlas.event.received", "atlas.run.updated" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "ok": true, "data": { "webhook_endpoint": { "id": "webhook_123", "endpoint_url": "https://abc.example.com/atlas/webhooks", "signing_secret": "mirai_atlas_secret" } } } } } } } } }, "/operator/developers/audit-events": { "get": { "tags": [ "Developer Console" ], "summary": "List recent audit events", "description": "Returns the most recent Atlas developer asset lifecycle events for the org.", "operationId": "developer_console_audit_events_list", "security": [ { "DeveloperConsoleBearer": [] } ], "x-mirai-visibility": "developer_console", "x-mirai-status": "implemented", "x-required-permissions": [ "atlas_api.audit.read" ], "x-required-scopes": [], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "ok": true, "data": { "events": [ { "id": "audit_123", "event_type": "atlas_api.service_account.key.created", "correlation_id": "corr_123" } ] } } } } } } } }, "/v1/atlas/channels": { "get": { "tags": [ "Atlas API v1" ], "summary": "List connected Atlas channels", "description": "Returns connected business channels and health metadata for the active Atlas principal organization.", "operationId": "atlas_channels_list", "security": [ { "AtlasBearer": [] } ], "x-mirai-visibility": "public_api", "x-mirai-status": "implemented", "x-required-permissions": [], "x-required-scopes": [ "atlas.channels.read" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "ok": true, "data": { "channels": [ { "id": "chan_123", "channel": "whatsapp", "display_name": "+65 9000 0000", "status": "connected" } ] } } } } } } } }, "/v1/atlas/knowledge": { "get": { "tags": [ "Atlas API v1" ], "summary": "List Atlas Knowledge documents", "description": "Lists knowledge documents available to the active Atlas principal for shared RAG grounding.", "operationId": "atlas_knowledge_list", "security": [ { "AtlasBearer": [] } ], "x-mirai-visibility": "public_api", "x-mirai-status": "implemented", "x-required-permissions": [], "x-required-scopes": [ "atlas.knowledge.read" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "ok": true, "data": { "documents": [ { "id": "doc_123", "title": "Reservation policy", "source_type": "text" } ] } } } } } } }, "post": { "tags": [ "Atlas API v1" ], "summary": "Create Atlas Knowledge content", "description": "Creates a knowledge document through the canonical queued ingest path so status remains truthful until worker indexing completes.", "operationId": "atlas_knowledge_create", "security": [ { "AtlasBearer": [] } ], "x-mirai-visibility": "public_api", "x-mirai-status": "implemented", "x-required-permissions": [], "x-required-scopes": [ "atlas.knowledge.write" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "title": "Reservation policy", "source_type": "text", "content": "Guests can book up to 30 days ahead." } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "ok": true, "data": { "document": { "id": "doc_123", "title": "Reservation policy", "training_status": "queued", "job_id": "job_123" } } } } } } } } }, "/v1/atlas/agents": { "get": { "tags": [ "Atlas API v1" ], "summary": "List Atlas agents", "description": "Lists Atlas-hosted and external-agent records for the active organization.", "operationId": "atlas_agents_list", "security": [ { "AtlasBearer": [] } ], "x-mirai-visibility": "public_api", "x-mirai-status": "implemented", "x-required-permissions": [], "x-required-scopes": [ "atlas.agents.read" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "ok": true, "data": { "agents": [ { "id": "agent_123", "name": "Front Desk", "status": "ready", "channels": [ "whatsapp" ] } ] } } } } } } }, "post": { "tags": [ "Atlas API v1" ], "summary": "Create an Atlas agent", "description": "Creates an agent and optionally links existing knowledge sources.", "operationId": "atlas_agents_create", "security": [ { "AtlasBearer": [] } ], "x-mirai-visibility": "public_api", "x-mirai-status": "implemented", "x-required-permissions": [], "x-required-scopes": [ "atlas.agents.write" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "name": "Front Desk", "description": "Booking helper", "source_ids": [ "doc_123" ], "channels": [ "whatsapp" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "ok": true, "data": { "agent": { "id": "agent_123", "name": "Front Desk", "status": "ready" } } } } } } } } }, "/v1/atlas/agents/:agentId/publish": { "post": { "tags": [ "Atlas API v1" ], "summary": "Publish an Atlas agent to the public directory", "description": "Updates listing metadata for an agent. Set is_listed to true to publish. Only the organization that owns the agent can update its listing.", "operationId": "atlas_agents_publish", "security": [ { "AtlasBearer": [] } ], "x-mirai-visibility": "public_api", "x-mirai-status": "implemented", "x-required-permissions": [], "x-required-scopes": [ "atlas.agents.publish" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "is_listed": true, "listing_category": "beauty", "listing_description": "AI sales agent for beauty and wellness businesses", "listing_slug": "beauty-sales-agent" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "ok": true, "data": { "agent": { "id": "agent_123", "name": "Front Desk", "is_listed": true, "listing_category": "beauty" } } } } } } } } }, "/v1/atlas/agents/directory": { "get": { "tags": [ "Atlas API v1" ], "summary": "List published agents in the Atlas directory", "description": "Returns all published agents from all organizations. No authentication required. Optionally filter by category.", "operationId": "atlas_agents_directory_read", "security": [ { "AtlasBearer": [] } ], "x-mirai-visibility": "public_api", "x-mirai-status": "implemented", "x-required-permissions": [], "x-required-scopes": [], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "ok": true, "data": { "agents": [ { "id": "agent_123", "name": "Front Desk", "organization_name": "Beauty Co", "listing_category": "beauty", "listing_description": "AI sales agent for beauty and wellness businesses", "listing_slug": "beauty-sales-agent" } ], "total_count": 42, "next_offset": 20 } } } } } } } }, "/v1/atlas/sessions": { "get": { "tags": [ "Atlas API v1" ], "summary": "List test sessions", "description": "Lists Atlas preview sessions for sandbox evaluation.", "operationId": "atlas_sessions_list", "security": [ { "AtlasBearer": [] } ], "x-mirai-visibility": "public_api", "x-mirai-status": "implemented", "x-required-permissions": [], "x-required-scopes": [ "atlas.sessions.read" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "ok": true, "data": { "sessions": [ { "id": "sess_123", "agent_id": "agent_123", "status": "active" } ] } } } } } } }, "post": { "tags": [ "Atlas API v1" ], "summary": "Create a test session", "description": "Creates a sandbox Atlas session tied to an optional agent.", "operationId": "atlas_sessions_create", "security": [ { "AtlasBearer": [] } ], "x-mirai-visibility": "public_api", "x-mirai-status": "implemented", "x-required-permissions": [], "x-required-scopes": [ "atlas.sessions.write" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "agent_id": "agent_123" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "ok": true, "data": { "session": { "id": "sess_123", "agent_id": "agent_123", "status": "active" } } } } } } } } }, "/v1/atlas/sessions/{sessionId}/messages": { "get": { "tags": [ "Atlas API v1" ], "summary": "List session messages", "description": "Returns the preview message transcript for a sandbox session.", "operationId": "atlas_session_messages_list", "security": [ { "AtlasBearer": [] } ], "x-mirai-visibility": "public_api", "x-mirai-status": "implemented", "x-required-permissions": [], "x-required-scopes": [ "atlas.sessions.read" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "ok": true, "data": { "messages": [ { "id": "msg_123", "role": "assistant", "content": "Reservation policy: Guests can book up to 30 days ahead." } ] } } } } } } }, "post": { "tags": [ "Atlas API v1" ], "summary": "Query a sandbox session", "description": "Adds a user message, runs keyword-backed Atlas Knowledge search, and returns a grounded preview reply.", "operationId": "atlas_session_messages_create", "security": [ { "AtlasBearer": [] } ], "x-mirai-visibility": "public_api", "x-mirai-status": "implemented", "x-required-permissions": [], "x-required-scopes": [ "atlas.sessions.write" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "query": "Can guests book for tomorrow?", "top_k": 3 } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "ok": true, "data": { "message": { "id": "msg_123", "role": "assistant", "content": "Reservation policy: Guests can book up to 30 days ahead." } } } } } } } } }, "/v1/atlas/conversations": { "get": { "tags": [ "Atlas API v1" ], "summary": "List live conversations", "description": "Returns normalized omnichannel conversation summaries for the active organization.", "operationId": "atlas_conversations_list", "security": [ { "AtlasBearer": [] } ], "x-mirai-visibility": "public_api", "x-mirai-status": "implemented", "x-required-permissions": [], "x-required-scopes": [ "atlas.conversations.read" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "ok": true, "data": { "conversations": [ { "id": "conv_123", "channel": "whatsapp", "state": "bot", "last_message_text": "Hi there" } ] } } } } } } } }, "/v1/atlas/events": { "post": { "tags": [ "Atlas API v1" ], "summary": "Receive inbound external-agent events", "description": "Accepts normalized inbound channel events, creates or updates the Mirai conversation, and emits signed outbound Atlas webhooks.", "operationId": "atlas_events_ingest", "security": [ { "AtlasBearer": [] } ], "x-mirai-visibility": "public_api", "x-mirai-status": "implemented", "x-required-permissions": [], "x-required-scopes": [ "atlas.events.write" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "idempotency_key": "evt_123", "channel": "whatsapp", "event_type": "message.received", "customer": { "phone_number": "+6590000000", "name": "Alex" }, "message": { "text": "Hi, I need a reservation" } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "ok": true, "data": { "accepted": true, "conversation_id": "conv_123" } } } } } } } }, "/v1/atlas/context/{conversationId}": { "get": { "tags": [ "Atlas API v1" ], "summary": "Fetch customer, conversation, and knowledge context", "description": "Returns normalized conversation state, customer profile, recent messages, and grounded Atlas Knowledge search results.", "operationId": "atlas_context_get", "security": [ { "AtlasBearer": [] } ], "x-mirai-visibility": "public_api", "x-mirai-status": "implemented", "x-required-permissions": [], "x-required-scopes": [ "atlas.context.read" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "ok": true, "data": { "conversation": { "id": "conv_123", "channel": "whatsapp" }, "customer": { "id": "cust_123", "name": "Alex" }, "recent_messages": [ { "id": "msg_123", "text": "Can I book tonight?" } ], "knowledge": [ { "chunk_id": "chunk_123", "title": "Reservation policy" } ] } } } } } } } }, "/v1/atlas/actions": { "post": { "tags": [ "Atlas API v1" ], "summary": "Submit an external-agent reply or action", "description": "Accepts replies, drafts, and handoff decisions, then routes reply delivery through Mirai-managed channels.", "operationId": "atlas_actions_execute", "security": [ { "AtlasBearer": [] } ], "x-mirai-visibility": "public_api", "x-mirai-status": "implemented", "x-required-permissions": [], "x-required-scopes": [ "atlas.actions.execute" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "idempotency_key": "act_123", "conversation_id": "conv_123", "action_type": "reply", "payload": { "text": "I can help book a table for tonight." } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "ok": true, "data": { "accepted": true, "delivery_state": "queued" } } } } } } } }, "/v1/atlas/messages": { "post": { "tags": [ "Atlas API v1" ], "summary": "Send a WhatsApp message to a phone number", "description": "Sends an outbound WhatsApp message, creating or reusing the customer and conversation for the active organization.", "operationId": "atlas_messages_send", "security": [ { "AtlasBearer": [] } ], "x-mirai-visibility": "public_api", "x-mirai-status": "implemented", "x-required-permissions": [], "x-required-scopes": [ "atlas.messages.send" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "idempotency_key": "msg_123", "phone_number": "+6590000000", "text": "Happy birthday! I can apply your 20% voucher to your next booking.", "category": "utility" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "ok": true, "data": { "conversation_id": "conv_123", "queued": true, "window_open": true, "outbox_id": "outbox_123", "phone_number": "+6590000000" } } } } } } } }, "/v1/atlas/runs": { "get": { "tags": [ "Atlas API v1" ], "summary": "List Atlas runtime runs", "description": "Lists event and action runs recorded through the public Atlas API surface.", "operationId": "atlas_runs_list", "security": [ { "AtlasBearer": [] } ], "x-mirai-visibility": "public_api", "x-mirai-status": "implemented", "x-required-permissions": [], "x-required-scopes": [ "atlas.runs.read" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "ok": true, "data": { "runs": [ { "id": "run_123", "operation_scope": "atlas.event", "event_type": "message.received", "status": "completed" } ] } } } } } } } }, "/v1/atlas/webhooks": { "get": { "tags": [ "Atlas API v1" ], "summary": "List outbound Atlas webhook subscriptions", "description": "Lists webhook endpoints owned by the active app or service account principal.", "operationId": "atlas_webhooks_list", "security": [ { "AtlasBearer": [] } ], "x-mirai-visibility": "public_api", "x-mirai-status": "implemented", "x-required-permissions": [], "x-required-scopes": [ "atlas.events.read" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "ok": true, "data": { "webhooks": [ { "id": "webhook_123", "endpoint_url": "https://abc.example.com/atlas/webhooks" } ] } } } } } } }, "post": { "tags": [ "Atlas API v1" ], "summary": "Register outbound Atlas event delivery", "description": "Registers a signed outbound webhook endpoint for the active app or service account principal.", "operationId": "atlas_webhooks_create", "security": [ { "AtlasBearer": [] } ], "x-mirai-visibility": "public_api", "x-mirai-status": "implemented", "x-required-permissions": [], "x-required-scopes": [ "atlas.events.read" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "endpoint_url": "https://abc.example.com/atlas/webhooks", "subscribed_events": [ "atlas.event.received", "atlas.run.updated" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "ok": true, "data": { "webhook": { "id": "webhook_123", "signing_secret": "mirai_atlas_secret" } } } } } } } } }, "/v1/atlas/tools/manifest": { "get": { "tags": [ "Atlas API v1" ], "summary": "Discover available Atlas tools", "description": "Returns tool definitions filtered by the caller's granted scopes. Use this to understand which tools the authenticated principal can call.", "operationId": "atlas_tools_manifest", "security": [ { "AtlasBearer": [] } ], "x-mirai-visibility": "public_api", "x-mirai-status": "implemented", "x-required-permissions": [], "x-required-scopes": [ "atlas.tools.manifest" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "ok": true, "data": { "tools": [ { "name": "search_knowledge", "description": "Search the knowledge base for answers to customer questions.", "scopes": [ "atlas.knowledge.read" ], "input_schema": { "type": "object", "properties": { "query": { "type": "string" } }, "required": [ "query" ] } } ] } } } } } } } }, "/operator/developers/billing/summary": { "get": { "tags": [ "Developer Console" ], "summary": "Read billing summary", "description": "Returns the current plan, current-calendar-month API usage broken down by event type, and the spending ledger for the billing period.", "operationId": "developer_console_billing_summary", "security": [ { "DeveloperConsoleBearer": [] } ], "x-mirai-visibility": "developer_console", "x-mirai-status": "implemented", "x-required-permissions": [], "x-required-scopes": [ "atlas.billing.read" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "ok": true, "data": { "plan": { "plan_type": "pay_as_you_go", "spending_limit_cents": 50000 }, "current_period_usage": [ { "event_type": "atlas.message.sent", "unit_count": 142, "cost_usd": 0.71 }, { "event_type": "atlas.run.completed", "unit_count": 389, "cost_usd": 1.945 } ], "spending": { "total_cost_usd": 2.655, "period_start": "2026-04-01T00:00:00Z", "period_end": "2026-04-30T23:59:59Z" } } } } } } } } }, "/operator/developers/billing/plan": { "post": { "tags": [ "Developer Console" ], "summary": "Change billing plan", "description": "Upgrades or downgrades the organization billing plan. Idempotent: calling with the same plan_type twice is safe. pay_as_you_go triggers a Stripe metered subscription; other plans cancel it.", "operationId": "developer_console_billing_plan", "security": [ { "DeveloperConsoleBearer": [] } ], "x-mirai-visibility": "developer_console", "x-mirai-status": "implemented", "x-required-permissions": [], "x-required-scopes": [ "atlas.billing.manage" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "plan_type": "pay_as_you_go" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "ok": true, "data": { "plan_type": "pay_as_you_go", "updated": true } } } } } } } }, "/operator/developers/billing/spending-limit": { "post": { "tags": [ "Developer Console" ], "summary": "Set monthly spending limit", "description": "Sets or clears the monthly spending limit in cents. Requires atlas.billing.manage scope.", "operationId": "developer_console_billing_spending_limit", "security": [ { "DeveloperConsoleBearer": [] } ], "x-mirai-visibility": "developer_console", "x-mirai-status": "implemented", "x-required-permissions": [], "x-required-scopes": [ "atlas.billing.manage" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "spending_limit_cents": 50000 } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "ok": true, "data": { "spending_limit_cents": 50000 } } } } } } } } } }