Skip to main content

​
Introduction

The Mission Control API is a REST API for orchestrating AI agents, managing tasks, tracking token usage, and monitoring system health. All endpoints return JSON and follow OpenAPI 3.1.0 specifications.

​
Base URL

The API is served from the same host as your Mission Control dashboard: 
http://localhost:3000/api
For production deployments, use your configured hostname: 
https://mission-control.example.com/api
The API uses relative URLs (/) in the OpenAPI specification. All endpoints are prefixed with /api/.

​
Architecture

Mission Control is built on:
  • Framework: Next.js 16 App Router
  • Database: SQLite with better-sqlite3 (WAL mode)
  • Real-time: WebSocket + Server-Sent Events (SSE)
  • Authentication: Session cookies + API keys + OAuth
  • Validation: Zod schemas with detailed error messages

​
Tech Stack

ComponentTechnology
FrameworkNext.js 16
LanguageTypeScript 5.7
DatabaseSQLite (WAL mode)
State ManagementZustand 5
ChartsRecharts 3
TestingVitest + Playwright

​
API Versioning

Version 1.2.0The current API version is 1.2.0. Mission Control follows semantic versioning:
  • Major: Breaking changes to request/response formats
  • Minor: New endpoints or optional parameters
  • Patch: Bug fixes and security updates
Mission Control is alpha software. APIs and database schemas may change between releases. Pin your version and review migration guides when upgrading.

​
Rate Limiting

API-wide rate limiting is enforced to prevent abuse:
  • Default limit: 100 requests per minute per IP
  • Trusted proxies: Configure MC_TRUSTED_PROXIES for X-Forwarded-For parsing
  • Rate limit headers: Check X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset

​
Rate Limit Response

When rate limited, you’ll receive: 
{
  "error": "Rate limit exceeded"
}
Status code: 429 Too Many Requests

​
Request Format

All POST, PUT, and PATCH requests must include: 
Content-Type: application/json

​
Example Request

curl -X POST https://mission-control.example.com/api/agents \
  -H "Content-Type: application/json" \
  -H "x-api-key: your-api-key" \
  -d '{
    "name": "researcher",
    "role": "Research and documentation agent",
    "status": "online"
  }'

​
Response Format

All responses return JSON with consistent error structures.

​
Success Response

{
  "agent": {
    "id": 42,
    "name": "researcher",
    "role": "Research and documentation agent",
    "status": "online",
    "created_at": 1709587200
  }
}

​
Error Response

{
  "error": "Invalid request",
  "details": [
    "name is required",
    "status must be one of: online, offline, busy, idle, error"
  ]
}

​
HTTP Status Codes

Mission Control uses standard HTTP status codes:
CodeMeaningDescription
200OKRequest succeeded
201CreatedResource created successfully
400Bad RequestInvalid request body or parameters
401UnauthorizedAuthentication required
403ForbiddenInsufficient permissions for this operation
404Not FoundResource does not exist
409ConflictResource already exists (e.g., duplicate username)
429Too Many RequestsRate limit exceeded
500Internal Server ErrorServer error (check logs)

​
Pagination

Endpoints that return lists support pagination:

​
Parameters

  • limit: Number of items per page (default: 50, max: 200)
  • offset: Number of items to skip (default: 0)

​
Example

curl "https://mission-control.example.com/api/agents?limit=20&offset=40" \
  -H "x-api-key: your-api-key"

​
Response

{
  "agents": [...],
  "total": 150,
  "page": 2,
  "limit": 20
}

​
Filtering

Many endpoints support query parameters for filtering:

​
Agents

GET /api/agents?status=online&role=researcher

​
Tasks

GET /api/tasks?status=in_progress&priority=high&assigned_to=researcher

​
Token Usage

GET /api/tokens?action=stats&timeframe=week

​
CSRF Protection

Mutating requests (POST, PUT, DELETE, PATCH) validate the Origin header:
  • Origin must match the request host
  • Prevents cross-site request forgery attacks
  • Session cookie authentication only
API key authentication bypasses CSRF checks since keys are sent in headers, not cookies.

​
Network Access Control

In production, Mission Control enforces host allowlists:

​
Environment Variables

# Allow specific hosts (comma-separated)
MC_ALLOWED_HOSTS="mission-control.example.com,*.internal.example.com"

# Or allow any host (not recommended for production)
MC_ALLOW_ANY_HOST=1

​
Host Patterns

  • mission-control.example.com - Exact match
  • *.example.com - Wildcard subdomain (matches a.example.com, not example.com)
  • 192.168.* - IP prefix match
In production (NODE_ENV=production), access is denied by default unless explicitly allowed. Set MC_ALLOWED_HOSTS or deploy behind a reverse proxy.

​
Real-time Updates

Mission Control provides real-time updates via:

​
Server-Sent Events (SSE)

curl -N "https://mission-control.example.com/api/events" \
  -H "x-api-key: your-api-key"
Receive database change events: 
data: {"type":"agent.status","agent":"researcher","status":"busy"}

data: {"type":"task.created","id":42,"title":"Document API"}

​
WebSocket (Gateway)

For OpenClaw gateway connections: 
const ws = new WebSocket('ws://localhost:18789');
ws.send(JSON.stringify({
  type: 'authenticate',
  token: 'your-gateway-token'
}));

​
OpenAPI Specification

Download the full OpenAPI 3.1.0 specification: 
curl https://mission-control.example.com/api/docs > openapi.json
Interactive API explorer available at: 
https://mission-control.example.com/docs

​
Next Steps

Authentication

Learn about session cookies, API keys, and OAuth

Agents

Manage agent lifecycle and status

Tasks

Create and track agent tasks

Tokens

Monitor token usage and costs