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

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

string

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

integer

default:"50"

Maximum number of agents to return (max: 200)

integer

default:"0"

Number of agents to skip for pagination

Response Fields

array

Array of agent objects

Show Agent Object

integer

Unique agent identifier

string

Agent display name

string

Agent role or specialty

string

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

string

Gateway session identifier

string

Agent personality and instruction configuration

object

Agent configuration including model, tools, sandbox settings

integer

Unix timestamp of last heartbeat

integer

Unix timestamp of agent creation

integer

Unix timestamp of last update

object

Task statistics for this agent

Show Task Stats

integer

Total tasks

integer

Assigned tasks

integer

Tasks in progress

integer

Completed tasks

integer

Total number of agents matching filters

integer

Current page number

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"

const response = await fetch('/api/agents?status=online&limit=10', {
  headers: {
    'x-api-key': 'your-api-key'
  }
});
const data = await response.json();

import requests

response = requests.get(
    'https://your-domain.com/api/agents',
    params={'status': 'online', 'limit': 10},
    headers={'x-api-key': 'your-api-key'}
)
agents = response.json()

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

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

string

required

Unique agent name

string

required

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

string

Gateway session key for connection

string

Agent personality and instruction configuration

string

default:"offline"

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

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

string

Template identifier to initialize agent configuration

object

Gateway-specific configuration to merge with config

boolean

default:"false"

Whether to write agent configuration to gateway config file

Response Fields

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"
  }'

const response = await fetch('/api/agents', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-api-key': 'your-api-key'
  },
  body: JSON.stringify({
    name: 'code-reviewer',
    role: 'qa',
    config: {
      model: 'claude-sonnet-4',
      tools: ['bash', 'read', 'edit']
    },
    soul_content: 'You are a meticulous code reviewer.',
    status: 'online'
  })
});
const data = await response.json();

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

Missing required fields or invalid data

Authentication required

Insufficient permissions (requires operator role)

Agent name already exists

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

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

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

string

required

Agent name to update

string

New agent status

string

Last activity description

object

Updated configuration object

string

Updated session key

string

Updated soul configuration

string

Updated role

Response

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

No fields to update or invalid data

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

string

New agent name

string

New role

string

New status

object

Updated configuration

string

New session key

string

Updated soul content

Response

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

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

string

Agent name

array

Array of task objects assigned to this agent

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

boolean

Whether heartbeat was triggered

Get Agent Soul

GET /api/agents/{id}/soul

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

Response

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

string

required

New soul configuration

Response

boolean

Whether update was successful

Get Agent Memory

GET /api/agents/{id}/memory

Retrieve agent’s memory data.

Response

object

Agent memory data structure

Update Agent Memory

PUT /api/agents/{id}/memory

Update agent’s memory data.

Authorization: Operator role required

Request Body

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

string

Reason for waking the agent

Response

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

string

required

Sender agent name

string

required

Recipient agent name

string

required

Message content

string

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

Response

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

string

Filter by specific agent name

integer

default:"50"

Maximum number of messages to return

Response

array

Array of message objects

Show Message Object

integer

Message ID

string

Sender agent

string

Recipient agent

string

Message content

string

Message type

integer

Unix timestamp

Sync Agents from Gateway

POST /api/agents/sync

Synchronize agents from gateway configuration file.

Authorization: Operator role required

Response

integer

Total agents synced

integer

Number of new agents created

integer

Number of existing agents updated

Example Response

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

​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

POST /api/agents/sync

​Response

​Example Response

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