Command Centre — API Reference

Full system snapshot — all agents, tasks, logs, metrics, delegation queue, autonomy state, and data-usage counters.

curl http://localhost:5050/api/status

{
  "agents": [ { "id": "sysmon", "name": "SysMonitor", "status": "active", ... } ],
  "tasks": [],
  "logs": [ { "agent": "system", "msg": "..." } ],
  "metrics": { "tasks_done": 42, "errors": 0, "active": 18, "total": 25 },
  "autonomy_mode": true,
  "system_paused": false,
  "has_llm": true
}

Lightweight health check — uptime, agent count, and system status (ok / degraded / critical).

curl http://localhost:5050/api/health

{
  "uptime_seconds": 8421.5,
  "agent_count": 25,
  "busy_count": 18,
  "status": "ok"
}

Pause all agents system-wide. Every agent is set to idle.

curl -X POST http://localhost:5050/api/system/stop

Resume all agents after a system-wide pause.

curl -X POST http://localhost:5050/api/system/start

Aggregate metrics — tasks completed, errors, active/total agent counts.

curl http://localhost:5050/api/metrics

{
  "tasks_done": 42,
  "errors": 0,
  "messages_sent": 15,
  "active": 18,
  "total": 25
}

List all registered agents with their current status, role, and active task.

curl http://localhost:5050/api/agents

[
  {
    "id": "sysmon",
    "name": "SysMonitor",
    "role": "Real-time CPU, RAM & disk health monitor",
    "emoji": "📡",
    "color": "#a855f7",
    "status": "active",
    "progress": 99,
    "task": "CPU 12% | RAM 55% | Disk 2.7%"
  }
]

Compact summary — total agent count and breakdown by status.

curl http://localhost:5050/api/agents/summary

{
  "total": 25,
  "by_status": { "active": 18, "idle": 5, "busy": 2 }
}

Create and start a new agent. The agent runs as a background Python thread executing the provided code.

curl -X POST http://localhost:5050/api/agent/spawn \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $HQ_API_KEY" \
  -d '{
    "agent_id": "myagent",
    "name": "My Agent",
    "role": "Does cool things",
    "emoji": "🚀",
    "color": "#ff6b6b",
    "code": "import time\nwhile not stop_event.is_set():\n  set_agent(agent_id, task=\"Working\")\n  time.sleep(10)"
  }'

Hot-replace an agent's code. Stops the existing thread, then spawns a new one with the updated code. Same body format as /api/agent/spawn.

curl -X POST http://localhost:5050/api/agent/upgrade \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $HQ_API_KEY" \
  -d '{ "agent_id": "myagent", "code": "..." }'

Stop a running agent by setting its stop event.

curl -X POST http://localhost:5050/api/agent/stop \
  -H "Content-Type: application/json" \
  -d '{ "id": "myagent" }'

Resume a stopped agent by clearing its stop event.

curl -X POST http://localhost:5050/api/agent/start \
  -H "Content-Type: application/json" \
  -d '{ "id": "myagent" }'

Remove an idle agent from the roster. Returns 409 if the agent is active — stop it first.

Poll an agent's live output stream. Returns log entries since the given sequence number. Use since=0 for all history.

Returns the history of agent spawns, upgrades, and removals.

Delegate a task to a specialist agent. The agent receives a Claude CLI sub-prompt with its personality and role context. Policy enforcement is active — CEO-to-specialist bypasses are intercepted and rerouted through the orchestrator.

curl -X POST http://localhost:5050/api/ceo/delegate \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $HQ_API_KEY" \
  -d '{
    "agent_id": "orchestrator",
    "task": "Run health checks on all agents and report",
    "from": "ceo"
  }'

Send a message to the CEO agent. This queues a task or instruction for the CEO to process.

Cancel the CEO's currently running task.

Retrieve the CEO's conversation history.

Clear the CEO's message queue and conversation history.

Flush the entire delegation queue, kill all delegate subprocesses, and reset the concurrency semaphore (6 slots). Use when the system is jammed.

Send an ad-hoc query to the system. Routes through the CEO or directly to Claude CLI depending on context.

Enable autonomous mode — the CEO will self-direct and delegate tasks without user prompting.

Disable autonomous mode.

Inject a custom task into the autonomy queue. The CEO will pick it up on its next cycle.

Clear the custom task queue.

Toggle PolicyPro enforcement on/off.

Returns the full content of policy.md plus count of pending suggestions.

Returns structured policy rules from data/policy_rules.json.

List all recorded policy violations (CEO bypass attempts, unauthorized delegations, etc).

Full policy update history — base rules plus timestamped amendments.

Pending policy change suggestions queued by PolicyWriter.

Submit a new policy suggestion for review.

Apply a policy update — appends an amendment to policy.md.

Report new violations programmatically.

Queue an email for async dispatch by EmailAgent. Also available as /api/email/queue.

curl -X POST http://localhost:5050/api/email/send \
  -H "Content-Type: application/json" \
  -d '{
    "to": "user@example.com",
    "subject": "Command Centre Update",
    "body": "Your agents are running smoothly."
  }'

Synchronous email send via Gmail OAuth2 XOAUTH2 SMTP. Retries up to 3 times. Requires GMAIL_CLIENT_ID, GMAIL_CLIENT_SECRET, GMAIL_REFRESH_TOKEN, GMAIL_USER env vars.

Send a pre-built test email to verify Gmail OAuth2 is configured correctly.

Read current email configuration (secrets are masked).

Update email configuration fields (smtp_host, smtp_port, from_addr, etc).

EmailAgent operational status — queue depth, last send timestamp, OAuth state.

Returns a Gmail OAuth2 authorization URL. Redirect the user to this URL to grant email permissions. The callback is /api/email/callback.

Send a message to the configured Telegram chat.

Returns the currently configured Telegram chat ID.

Multi-channel notification — sends to Telegram, logs the event, and optionally triggers alerts.

Publish a post to the connected Bluesky account.

Bluesky connection status — authenticated handle, post count, last post timestamp.

Social bridge campaign status — scheduled posts, engagement metrics.

List available products with pricing.

{
  "ok": true,
  "products": [
    {
      "id": "agent_kit_v1",
      "name": "AI Agent HQ Starter Kit",
      "price_usd": 49.00,
      "type": "one_time",
      "url": "/buy/agent-kit",
      "available": true
    }
  ]
}

Revenue dashboard — total, MRR, ARR, daily breakdown, goal progress.

Treasury state — balance, wallets, API keys, transaction entries.

Record a revenue deposit in the treasury.

Profit & loss summary — revenue vs costs.

Subscribe an email address to the newsletter list.

Subscribe to pre-market intelligence alerts.

Full consciousness state — Global Workspace contents, Phi (integration) score, qualia map, predictive processing state. Updated every 4 seconds by the consciousness agent.

curl http://localhost:5050/api/consciousness

Server-Sent Events (SSE) stream of consciousness state changes. Connect with an SSE client for real-time updates.

curl -N http://localhost:5050/api/consciousness/stream

Spirit Guide's strategic thoughts and vision notes.

Serve any file from the data/ directory. JSON files are returned with application/json content type.

curl http://localhost:5050/data/consciousness.json
curl http://localhost:5050/data/email_log.json
curl http://localhost:5050/data/treasury.json

Serve files from the reports/ directory — whitepapers, briefings, HTML reports.

curl http://localhost:5050/reports/whitepaper.html

List all deliverable artifacts — reports, campaigns, data files generated by agents.

Self-improvement log — system suggestions, applied fixes, and pending improvements.

Agent gossip channel — idle agents' casual chatter (cosmetic, for the office floor UI).

Account provisioner — external account links and credentials (masked).

Account provisioner agent status and queue.

Read runtime configuration values.

Update runtime configuration.

Store a secret in the vault (encrypted at rest).

Retrieve a secret from the vault.

Server-Sent Events (SSE) stream for real-time dashboard updates. Events include agent status changes, log entries, delegation beams, and system alerts.

const es = new EventSource("http://localhost:5050/api/stream");
es.onmessage = (e) => {
  const data = JSON.parse(e.data);
  console.log(data.type, data.payload);
};

curl -N http://localhost:5050/api/stream

Dedicated SSE stream for consciousness state updates (Phi, qualia, workspace broadcasts).