Reference

HTTP API and ToolHost

The HTTP server exposes project observability, user control actions, SSE event streaming, and the container-facing ToolHost.

Server

suzumio serve --host 0.0.0.0 --port 39400

The current API is intended for local or trusted-network use. User-facing API authentication is not implemented in the first version. The container-facing tool route uses per-agent tokens.

Conventions

TopicBehavior
Base URLhttp://127.0.0.1:39400 by default.
Body formatJSON for POST routes except no-body lifecycle actions.
List limits?limit=n, capped at 500.
ErrorsValidation and runtime errors return plain text or JSON depending on the route path.
TokensAgent tokens are redacted from project and agent listing responses.

Health

GET /health

{
  "healthy": true
}

Projects

MethodPathDescription
GET/api/projectsList projects under SUZUMIO_ROOT. Each entry is a project summary.
GET/api/projects/:projectProject summary with redacted agents, recent turns, and recent messages.
curl http://127.0.0.1:39400/api/projects/demo

Project Objects

MethodPathDescription
GET/api/projects/:project/agentsAgent records with tokens redacted.
GET/api/projects/:project/messages?limit=100Recent messages.
GET/api/projects/:project/events?limit=200Recent events.
GET/api/projects/:project/turns?limit=100Recent turns.
GET/api/projects/:project/tool-calls?limit=100Recent tool calls.
GET/api/projects/:project/artifacts?limit=100Artifact registry.
GET/api/projects/:project/config/resolvedResolved YAML config as plain text.
GET/api/projects/:project/reportFinal report text if submitted, otherwise a short placeholder.

User Control Actions

MethodPathBodyDescription
POST/api/projects/:project/startEmptySet project status to running and tick scheduler.
POST/api/projects/:project/stopEmptySet project status to stopped.
POST/api/projects/:project/approveEmptySet project status to completed.
POST/api/projects/:project/request-changes{ "recipient": "pm", "body": "..." }Return project to running, send a P1 user message, and tick scheduler.
POST/api/projects/:project/messages{ "recipient": "pm", "priority": "P1", "body": "..." }Create a message and tick scheduler.
curl -X POST http://127.0.0.1:39400/api/projects/demo/messages \
  -H 'content-type: application/json' \
  -d '{"recipient":"pm","priority":"P1","body":"Start."}'

For /messages, body may include sender, recipient, channel, priority, and body. Use either recipient or channel. Priority defaults to P1.

SSE Stream

The event stream sends SQLite events as Server-Sent Events. It emits existing recent events first and polls for new events every two seconds.

GET /api/projects/:project/stream

event: message.created
data: { ...event row... }

ToolHost

The Docker runner uses POST /tool to execute project tools. This route is not a public user API.

POST /tool
{
  "project": "demo",
  "agentId": "pm",
  "turnId": "turn_...",
  "token": "agent-private-token",
  "tool": "messages.send",
  "input": {
    "recipient": "user",
    "priority": "P1",
    "body": "Done."
  }
}

The ToolHost verifies that the token matches the agent and that the requested tool is in the agent allowlist. It records a tool_calls row before execution and updates it after success or failure.

Core Tool Inputs

messages.send

{
  "recipient": "worker",
  "channel": "#project",
  "priority": "P2",
  "body": "Markdown message"
}

Use either recipient or channel, not both. Channels must be declared in project config.

artifacts.publish

{
  "path": "relative/path/in/workspace.txt",
  "name": "optional-name.txt",
  "description": "What this artifact contains"
}

The path is relative to the agent workspace. Suzumio copies the file into the project artifact registry and records a SHA-256 hash.

artifacts.list

{}

completion.submit

{
  "report": "# Final Report\n\n..."
}

This writes final-report.md, marks the project submitted, and waits for user approval.

WebUI

The root path / serves the embedded WebUI. It calls the API routes above and refreshes periodically. The first version is intentionally simple: project selector, message form, agents, messages, turns, events, and artifacts.

Next: Roadmap.