HTTP API reference
The daemon exposes its surface over three protocols, all on the
same TCP port (default 8000):
| Protocol | Page | Use it for |
|---|---|---|
REST (/api/...) | REST API | App lifecycle, sessions, messages, workspace, credentials, secrets, MCP, hub, modules. Synchronous request / response. |
| Socket.IO | Socket.IO | Live event stream: turn progress, tool calls, tool results, hooks, workspace updates, agent fan-out. |
| DAP | DAP (Debug Adapter Protocol) | Optional debugger interface for stepping through agent loops. |
Plus the YAML language JSON Schema for IDE integration (covers
the canonical schema_version: 2 shape; filename kept for URL
stability):
The OpenAPI spec is served by the running daemon under
/openapi.json when expose_docs: true (development) and is not
shipped with the static documentation.
Authentication
Every /api/* request requires a Bearer token. The token is issued
by the auth flow described in Auth.
The five "always public" paths are:
(health probe),(liveness probe)/.well-known/*/docs,/redoc,/openapi.json/auth/*
There is no loopback bypass in the registered middleware. An
in-process tool that calls http://127.0.0.1:8000/api/... MUST
attach a valid JWT, or use the in-process Python module dispatch
(the default for filesystem, memory, MCP, etc.). Comments in older
parts of the codebase that describe a loopback bypass refer to a
class that is no longer wired in.
Versioning
The REST surface follows a /api/{resource}/v{N} style for
versioned resources (notably (daemon API)). v1 endpoints are
still served for backward compatibility but new clients should
target the latest version. See versioning.
Rate limits
Rate limits are configured under daemon.rate_limit in
Configuration. The defaults are
generous; the daemon also enforces per-IP and per-user caps to
prevent runaway clients. Exceeding a limit returns
429 Too Many Requests with the relevant Retry-After header.