Agents API - Mission Control

Overview

The Agents API provides complete control over AI agent lifecycle, configuration, and orchestration. Agents represent autonomous AI workers that can execute tasks, communicate with each other, and maintain persistent state.

Authentication

All agent endpoints require authentication via:

Session Cookie: mc-session (set after login)
API Key: x-api-key header

Minimum role requirements vary by endpoint (viewer, operator, or admin).

List Agents

GET /api/agents

Retrieve a paginated list of agents with optional filtering by status and role.

Authorization: Viewer role required

Query Parameters

status

string

Filter by agent status

Show Allowed values

online - Agent is active and available
offline - Agent is not running
busy - Agent is executing a task
idle - Agent is online but inactive
error - Agent encountered an error

role

string

Filter by agent role (e.g., “developer”, “analyst”, “qa”)

limit

integer

default:"50"

Maximum number of agents to return (max: 200)

offset

integer

default:"0"

Number of agents to skip for pagination

Response Fields

agents

array

Array of agent objects

Show Agent Object

integer

Unique agent identifier

name

string

Agent display name

role

string

Agent role or specialty

status

string

Current agent status (online, offline, busy, idle, error)

session_key

string

Gateway session identifier

soul_content

string

Agent personality and instruction configuration

config

object

Agent configuration including model, tools, sandbox settings

last_seen

integer

Unix timestamp of last heartbeat

created_at

integer

Unix timestamp of agent creation

updated_at

integer

Unix timestamp of last update

taskStats

object

Task statistics for this agent

Show Task Stats

total

integer

Total tasks

assigned

integer

Assigned tasks

in_progress

integer

Tasks in progress

completed

integer

Completed tasks

total

integer

Total number of agents matching filters

page

integer

Current page number

limit

integer

Number of agents per page

Example Request

curl -X GET "https://your-domain.com/api/agents?status=online&limit=10" \
  -H "x-api-key: your-api-key"

Example Response

{
  "agents": [
    {
      "id": 1,
      "name": "code-reviewer",
      "role": "qa",
      "status": "online",
      "session_key": "session-abc123",
      "config": {
        "model": "claude-sonnet-4",
        "tools": ["bash", "read", "edit"]
      },
      "last_seen": 1709856000,
      "created_at": 1709000000,
      "updated_at": 1709856000,
      "taskStats": {
        "total": 45,
        "assigned": 2,
        "in_progress": 1,
        "completed": 42
      }
    }
  ],
  "total": 1,
  "page": 1,
  "limit": 10
}

Error Responses

401 Unauthorized

Authentication required or invalid credentials

Create Agent

POST /api/agents

Create a new AI agent with specified configuration.

Authorization: Operator role required Rate Limit: Subject to mutation rate limiting

Request Body

name

string

required

Unique agent name

role

string

required

Agent role or specialty (e.g., “developer”, “qa”, “analyst”)

session_key

string

Gateway session key for connection

soul_content

string

Agent personality and instruction configuration

status

string

default:"offline"

Initial agent status: online, offline, busy, idle, error

config

object

Agent configuration object

Show Config Options

model: LLM model identifier (e.g., “claude-sonnet-4”)
tools: Array of enabled tools
identity: Agent identity configuration
sandbox: Sandbox environment settings
memorySearch: Memory search configuration

template

string

Template identifier to initialize agent configuration

gateway_config

object

Gateway-specific configuration to merge with config

write_to_gateway

boolean

default:"false"

Whether to write agent configuration to gateway config file

Response Fields

agent

object

Created agent object with all fields (same structure as List Agents)

Example Request

curl -X POST "https://your-domain.com/api/agents" \
  -H "Content-Type: application/json" \
  -H "x-api-key: your-api-key" \
  -d '{
    "name": "code-reviewer",
    "role": "qa",
    "config": {
      "model": "claude-sonnet-4",
      "tools": ["bash", "read", "edit"]
    },
    "soul_content": "You are a meticulous code reviewer.",
    "status": "online"
  }'

Example Response

{
  "agent": {
    "id": 2,
    "name": "code-reviewer",
    "role": "qa",
    "status": "online",
    "config": {
      "model": "claude-sonnet-4",
      "tools": ["bash", "read", "edit"]
    },
    "soul_content": "You are a meticulous code reviewer.",
    "created_at": 1709856400,
    "updated_at": 1709856400,
    "taskStats": {
      "total": 0,
      "assigned": 0,
      "in_progress": 0,
      "completed": 0
    }
  }
}

Error Responses

400 Bad Request

Missing required fields or invalid data

401 Unauthorized

Authentication required

403 Forbidden

Insufficient permissions (requires operator role)

409 Conflict

Agent name already exists

429 Too Many Requests

Rate limit exceeded

Get Agent by ID

GET /api/agents/{id}

Retrieve detailed information about a specific agent.

Authorization: Viewer role required

Path Parameters

integer

required

Agent ID

Response

agent

object

Complete agent object (same structure as List Agents)

Example Request

cURL

curl -X GET "https://your-domain.com/api/agents/1" \
  -H "x-api-key: your-api-key"

Error Responses

404 Not Found

Agent does not exist

Update Agent

PUT /api/agents

Update agent status and configuration by name.

Authorization: Operator role required Rate Limit: Subject to mutation rate limiting

Request Body

name

string

required

Agent name to update

status

string

New agent status

last_activity

string

Last activity description

config

object

Updated configuration object

session_key

string

Updated session key

soul_content

string

Updated soul configuration

role

string

Updated role

Response

success

boolean

Whether the update was successful

Example Request

cURL

curl -X PUT "https://your-domain.com/api/agents" \
  -H "Content-Type: application/json" \
  -H "x-api-key: your-api-key" \
  -d '{
    "name": "code-reviewer",
    "status": "busy",
    "last_activity": "Reviewing pull request #123"
  }'

Error Responses

400 Bad Request

No fields to update or invalid data

404 Not Found

Agent not found

Update Agent by ID

PUT /api/agents/{id}

Update agent configuration using agent ID.

Path Parameters

integer

required

Agent ID

Request Body

name

string

New agent name

role

string

New role

status

string

New status

config

object

Updated configuration

session_key

string

New session key

soul_content

string

Updated soul content

Response

agent

object

Updated agent object

Delete Agent

DELETE /api/agents/{id}

Permanently delete an agent.

Authorization: Operator role required

Path Parameters

integer

required

Agent ID to delete

Response

success

boolean

Whether deletion was successful

Example Request

cURL

curl -X DELETE "https://your-domain.com/api/agents/1" \
  -H "x-api-key: your-api-key"

Agent Heartbeat

GET /api/agents/{id}/heartbeat

Check for pending work items (tasks and messages) assigned to an agent.

Authorization: Viewer role required

Path Parameters

integer

required

Agent ID

Response

agent

string

Agent name

pending_tasks

array

Array of task objects assigned to this agent

messages

array

Array of pending messages for this agent

Example Request

cURL

curl -X GET "https://your-domain.com/api/agents/1/heartbeat" \
  -H "x-api-key: your-api-key"

Example Response

{
  "agent": "code-reviewer",
  "pending_tasks": [
    {
      "id": 10,
      "title": "Review auth module",
      "status": "assigned",
      "priority": "high"
    }
  ],
  "messages": [
    {
      "from": "task-manager",
      "content": "New task assigned",
      "type": "notification"
    }
  ]
}

Trigger Heartbeat

POST /api/agents/{id}/heartbeat

Manually trigger an agent heartbeat check.

Response

success

boolean

Whether heartbeat was triggered

Get Agent Soul

GET /api/agents/{id}/soul

Retrieve agent’s soul configuration (personality and instructions).

Response

soul_content

string

Agent soul configuration text

Example Response

{
  "soul_content": "You are a meticulous code reviewer focused on security and best practices."
}

Update Agent Soul

PUT /api/agents/{id}/soul

Update agent’s soul configuration.

Authorization: Operator role required

Request Body

soul_content

string

required

New soul configuration

Response

success

boolean

Whether update was successful

Get Agent Memory

GET /api/agents/{id}/memory

Retrieve agent’s memory data.

Response

memory

object

Agent memory data structure

Update Agent Memory

PUT /api/agents/{id}/memory

Update agent’s memory data.

Authorization: Operator role required

Request Body

memory

object

required

New memory data

Wake Agent

POST /api/agents/{id}/wake

Wake an idle agent and optionally provide a reason.

Authorization: Operator role required

Request Body

reason

string

Reason for waking the agent

Response

success

boolean

Whether agent was woken

Send Agent Message

POST /api/agents/message

Send a message between agents for inter-agent communication.

Authorization: Operator role required

Request Body

from

string

required

Sender agent name

string

required

Recipient agent name

content

string

required

Message content

type

string

Message type (e.g., “notification”, “request”)

Response

success

boolean

Whether message was sent

integer

Message ID

Example Request

cURL

curl -X POST "https://your-domain.com/api/agents/message" \
  -H "Content-Type: application/json" \
  -H "x-api-key: your-api-key" \
  -d '{
    "from": "task-manager",
    "to": "code-reviewer",
    "content": "Please review PR #123",
    "type": "request"
  }'

Get Agent Communications

GET /api/agents/comms

Retrieve communication history between agents.

Query Parameters

agent

string

Filter by specific agent name

limit

integer

default:"50"

Maximum number of messages to return

Response

messages

array

Array of message objects

Show Message Object

integer

Message ID

from_agent

string

Sender agent

to_agent

string

Recipient agent

content

string

Message content

type

string

Message type

created_at

integer

Unix timestamp

Sync Agents from Gateway

POST /api/agents/sync

Synchronize agents from gateway configuration file.

Authorization: Operator role required

Response

synced

integer

Total agents synced

created

integer

Number of new agents created

updated

integer

Number of existing agents updated

Example Response

{
  "synced": 5,
  "created": 2,
  "updated": 3
}

Overview

Core Resources

Monitoring

Integrations

Administration

​Overview

​Authentication

​List Agents

GET /api/agents

​Query Parameters

​Response Fields

​Example Request

​Example Response

​Error Responses

​Create Agent

POST /api/agents

​Request Body

​Response Fields

​Example Request

​Example Response

​Error Responses

​Get Agent by ID

GET /api/agents/{id}

​Path Parameters

​Response

​Example Request

​Error Responses

​Update Agent

PUT /api/agents

​Request Body

​Response

​Example Request

​Error Responses

​Update Agent by ID

PUT /api/agents/{id}

​Path Parameters

​Request Body

​Response

​Delete Agent

DELETE /api/agents/{id}

​Path Parameters

​Response

​Example Request

​Agent Heartbeat

GET /api/agents/{id}/heartbeat

​Path Parameters

​Response

​Example Request

​Example Response

​Trigger Heartbeat

POST /api/agents/{id}/heartbeat

​Response

​Get Agent Soul

GET /api/agents/{id}/soul

​Response

​Example Response

​Update Agent Soul

PUT /api/agents/{id}/soul

​Request Body

​Response

​Get Agent Memory

GET /api/agents/{id}/memory

​Response

​Update Agent Memory

PUT /api/agents/{id}/memory

​Request Body

​Wake Agent

POST /api/agents/{id}/wake

​Request Body

​Response

​Send Agent Message

POST /api/agents/message

​Request Body

​Response

​Example Request

​Get Agent Communications

GET /api/agents/comms

​Query Parameters

​Response

​Sync Agents from Gateway

Overview

Authentication

List Agents

Query Parameters

Response Fields

Example Request

Example Response

Error Responses

Create Agent

Request Body

Response Fields

Example Request

Example Response

Error Responses

Get Agent by ID

Path Parameters

Response

Example Request

Error Responses

Update Agent

Request Body

Response

Example Request

Error Responses

Update Agent by ID

Path Parameters

Request Body

Response

Delete Agent

Path Parameters

Response

Example Request

Agent Heartbeat

Path Parameters

Response

Example Request

Example Response

Trigger Heartbeat

Response

Get Agent Soul

Response

Example Response

Update Agent Soul

Request Body

Response

Get Agent Memory

Response

Update Agent Memory

Request Body

Wake Agent

Request Body

Response

Send Agent Message

Request Body

Response

Example Request

Get Agent Communications

Query Parameters

Response

Sync Agents from Gateway

Response

Example Response