HTTP API

• Where. 127.0.0.1 and the port in runtime.json ([api] port, 0 for a free one).
• Auth. Authorization: Bearer <token>, the token in api_token in the config directory. Only GET /v1/health is open, and it returns {"status": "ok"}. Agent routes take an agent token (oaken_agent_...) instead, and no other route accepts one.
• Host. Must be 127.0.0.1:<port> or localhost:<port>, else 400.
• Origin. A POST from another origin, or with Sec-Fetch-Site: cross-site, is 403. There are no CORS headers unless one development origin is configured.
• Content type. A POST must be application/json, else 415.
• Limits. Body size (413), request rate on mutating calls (429), concurrent calls (429).
• Caller class. X-Oaken-Client: cli (the default), ui or mcp. It can lower privilege and never raise it: mcp makes the call an agent's, so it cannot confirm by saying so. Anything else is 400.
• Errors. {"code": "...", "message": "..."}. Messages never contain mail text.

The MCP server is not in this document. When [api] mcp = true it is a separate door on the same listener, /mcp, with its own token and limits, and with the swarm on, /mcp/agent for agent tokens. See Connect an AI client.

POST /v1/operations/{name} takes input and answers ``request_id, status, output?.

status is ok when the operation ran, or confirmation_required for a mutation that was not confirmed: nothing has changed, and proposal says what would, with a confirmation_token. A person at the CLI or UI may send confirm: true. An agent calls again with the token. Status codes: 422 input or result does not validate, 403 not permitted, 404 unknown, 409 conflict, 429 quota, 502 a plugin or provider failed.

Each operation's input and output are in Reference: Operations, and as JSON Schema in the OpenAPI document and in GET /v1/operations.

GET /v1/events is server-sent events. Each frame has an id (a number), an event (the type below) and data (one line of JSON: ids and counts, never message text). Send Last-Event-ID to resume from the in-memory ring. If that id is older than the ring, or from before core restarted, a gap event comes first, meaning fetch state again. A quiet stream sends : heartbeat comments.

Authenticated by an agent token, never by the API token. See the swarm.

POST /v1/agent/jobs/claim

Lease the best runnable job of the agent's kinds, or none.

• Request: kinds?
• Response: job

POST /v1/agent/jobs/{job_id}/heartbeat

Extend the lease; says whether the job was cancelled.

• Request: none
• Response: ok?, cancel_requested

POST /v1/agent/jobs/{job_id}/complete

Finish the job with a result that matches its kind's schema.

• Request: result?, produced_by?
• Response: ok?

POST /v1/agent/jobs/{job_id}/fail

Give the job back with an error; core decides whether to retry.

• Request: error, permanent?
• Response: status