The runtime serves HTTP on 127.0.0.1:4741 by default. Set CONDENSATE_AGENTS_PORT to change the port. The listener binds to loopback only. Remote callers reach it through Tailscale Serve or another local front.
This page lists the runtime's HTTP routes, grouped by what they do, and the error codes a program can branch on. The SDK wraps most of them and decodes their responses, so prefer it when you can. The request bodies and response schemas are defined in packages/agents-host/src/http.ts and in the SDK. HTTP route index lists every route on the runtime's listener, generated from the routers.
The optional engine field on a spawn selects the agent that runs the thread: Claude Code (claude), Codex (codex), or Condensate's own agent (pi). Without it, the host picks the engine from the model.
Errors
Refusals return JSON with an error message. The refusals a program needs to branch on also carry a code, listed below. When a code is present, branch on it, not on the message text. Simple input errors, such as a bad limit or cursor, return a 400 with only error.
| Status | Code | Meaning |
|---|---|---|
| 400 | spawn-cwd-required | A build thread has no cwd. Pass a worktree. |
| 400 | spawn-cwd-fenced | The cwd sits inside a checkout the host fences off. |
| 400 | account-not-in-roster | The spec names an account outside the workspace's account list, or, with no workspace, an account a workspace claims. The body lists the workspace's accounts. |
| 400 | model-not-allowed | The model is outside the workspace's allowed list. The body lists the allowed models. |
| 409 | not-a-head | A role change names a thread that is not a head. |
| 429 | session-cap | The host is at its live session cap. Retry after Retry-After. |
| 429 | thread-list-rate-limited | The client has spent its budget for first-page listings. Retry after Retry-After. |
| 503 | draining | The host is draining for a restart. Retry after Retry-After. |
| 503 | spawns-paused | New spawns are paused because free disk space is low. Retry after Retry-After. |
A path no route claims returns a 404 with { "error", "build" }. build is the commit the host runs, the same one GET /health reports, so a route missing from an older build is easy to spot.
Read threads
| Method | Route | Purpose |
|---|---|---|
| GET | /threads | A page of thread summaries. Query: limit (default 50; values above 200 are clamped to 200), after (the nextAfter cursor), sort (created, the default, or recent), archived (live, the default, archived or all), role, type, workspace, parent (one thread's children), attached (threads held by an attached seat), and seats (open, the default, or all). |
| GET | /threads/:id | The thread row, its stage, the cost so far and the archive flag. |
| GET | /threads/:id/tail | A page of the durable event log. after=<seq> reads forward. before=<seq> reads older events, newest first. limit defaults to 200 and caps at 1000. wait=<ms> holds the request open for new events, up to 30 seconds. |
| GET | /threads/:id/follow | Server-sent durable events. Resumes from after, or from the Last-Event-ID header. |
| GET | /threads/:id/stream | Server-sent live deltas. Nothing is replayed, and a slow reader loses its oldest frames. |
| GET | /threads/:id/agui | The thread as an AG-UI event stream, from after=<seq>. |
| GET | /threads/:id/agui-page | One reverse page of the log as AG-UI frames, for chat clients that open at the end and page back. |
| GET | /threads/:id/turn | Whether a turn is running. |
| GET | /threads/:id/head | The thread's type and metadata, including its seat lease. |
| GET | /threads/:id/steering | Every steering turn in the thread, oldest first. |
| GET | /threads/:id/attachments | The thread's attachments. |
| GET | /threads/:id/memory | The memory recorded for the thread. |
| GET | /threads/:id/tool-results/:seq | The full body of one tool result. |
| GET | /threads/:id/operations, /operations/:operation | Delegations, subscription edges and long actions, or one of them. POST on the same paths starts an operation or reports its outcome. A second outcome for a finished operation returns 409 operation-settled. |
| GET | /threads/:id/subscriptions | The thread's subscriptions. |
| GET | /threads/:id/compact | Compaction status. |
Use after for forward reads and before for older history, and keep the two cursors apart. A forward page returns events, nextAfter and hasMore. A reverse page returns prevBefore and hasMore.
Poll the tail or follow route for changes in one thread. To watch the list, follow GET /workspaces/:name/changes and re-read only the threads that changed. The first page of GET /threads is rate-limited per client, keyed on the caller's address and its x-condensate-client header (or User-Agent), so repeated full-list polling gets a 429.
curl -fsS 'http://127.0.0.1:4741/threads?limit=20'
curl -fsS 'http://127.0.0.1:4741/threads/THREAD_ID/tail?limit=20'
Replace THREAD_ID with an ID from a listing response.
Start work
| Method | Route | Purpose |
|---|---|---|
| POST | /spawn | Create a thread from a spawn spec. Returns { threadId }. Refused while the host is draining or spawns are paused. |
| POST | /threads/:id/messages | Append a message and return 202 with its seq and ts, before any model runs. Set hold: true to keep the message held for editing with PATCH or DELETE /threads/:id/messages/:seq. Use from to name a program that sent text no person typed. |
| POST | /threads/:id/send | Send a message and wait for the reply. With async: true it behaves like messages and returns 202. |
| POST | /threads/:id/fork | Branch the conversation. The child continues the parent as it stood at atSeq. |
| POST | /threads/:id/loop, /loop/continue, /loop/stop | Start, continue or stop a loop on the thread. GET /threads/:id/loop reports its state. |
| GET, POST | /threads/:id/seats | List the thread's seats, or join a new one. DELETE /threads/:id/seats/:name removes a seat. |
| POST | /threads/:id/seats/replace | Change a seat's engine, model or placement. The seat keeps its name and its history. Returns changed: false when nothing differs. |
| PUT | /threads/:id/seat-lease | Record the lease that holds the thread. Body { "seatLease": "<id>" }, or null to clear it. |
| POST | /threads/:id/handoff | Offer the thread to another seat. Then read GET /threads/:id/handoffs, and answer with POST /threads/:id/handoffs/:fromSeq/accept or /decline. |
| POST | /threads/:id/compact | Compact the thread's context now. |
| POST | /threads/:id/events, /gate, /merge | Write cycle events for review and merge flows. |
| POST | /threads/:id/subscriptions | Subscribe to the thread's events. The body can name a filter, a note and a deliver target. DELETE /threads/:id/subscriptions/:watch removes one. |
| POST | /threads/:id/role | Retire a head to chat. No other role change is accepted. |
| POST | /threads/:id/ui/generate | Generate an interface for the thread. |
These routes have side effects, and each has its own body schema. Use the SDK methods, or read the schema in http.ts, rather than guessing a body from the route name.
Acceptance means the host recorded the request. It does not mean the work succeeded. Read the durable log after an accepted request to see the outcome.
Control a turn
| Method | Route | Purpose |
|---|---|---|
| POST | /threads/:id/interrupt | Stop the running turn. |
| POST | /threads/:id/approvals/:approvalId | Resolve a tool approval. Body { "decision": "allow" } or { "decision": "deny" }. An approval that is already closed answers with code: approval-closed. |
| GET | /threads/:id/questions/:requestId | The status of a question the seat asked. |
| POST | /threads/:id/questions/:requestId/answer, /dismiss, /continue | Answer a question, dismiss it, or continue without an answer. |
| POST | /threads/:id/recover | Recover a thread. |
| DELETE | /threads/:id?reason= | Retire a thread. Nothing is deleted. The host appends one archive event to the thread's log. |
| POST | /threads/:id/restore | Bring a retired thread back. Returns 409 when the workspace's head slot was taken in the meantime. |
Workspaces and memory
| Method | Route | Purpose |
|---|---|---|
| GET | /workspaces | The configured workspaces. |
| GET | /workspaces/:name | One workspace, with its GitHub slug. |
| PUT | /workspaces/:name/policy | Replace the workspace policy. |
| GET | /workspaces/:name/head | The thread that holds the workspace's head role. |
| GET | /workspaces/:name/approvals | Every tool call waiting on approval in the workspace, each with the thread it stops. |
| GET | /workspaces/:name/questions | Open questions across the workspace. |
| GET | /workspaces/:name/events | Server-sent workspace events. |
| GET | /workspaces/:name/changes | Server-sent changes to the workspace's threads. Name the threads to watch with threads. |
| GET | /workspaces/:name/tail | Recent events across the workspace. |
| POST | /workspaces/:name/memory/recall, /retain, /reflect | Recall, store and reflect on workspace memory. |
| GET | /workspaces/:name/memory | Browse workspace memory. |
A workspace has one head. A POST /spawn that asks for a second head in the same workspace is refused with a 409.
Review rooms and pull requests
| Method | Route | Purpose |
|---|---|---|
| POST | /workspaces/:name/rooms | Arm a review room for a PR, or adopt an existing one by key. |
| GET | /rooms/:id | The room's state and its seats. |
| GET | /workspaces/:name/rooms?repo=&pr= | Find a PR's room and its newest round. |
| GET | /rooms/capabilities | Whether the verdict poster is available. |
| POST | /rooms/:id/rounds | Fire a review round. Body { "prompt": "...", "seat": "..." }, both optional. Returns 409 when the room is not armed, or a round is running or the reviewer is busy. |
| GET | /rooms/:id/rounds/:n | One round. |
| POST | /rooms/:id/finalize | Post a round's verdict as a GitHub review. Returns 409 when the verdict is not ready, has been superseded, or is stale. |
| POST | /workspaces/:name/prs/:number/agents | Start a build thread on the PR's branch, in a worktree the runtime owns. |
| GET | /workspaces/:name/prs/:number/receipt?repo= | A read-only merge receipt: the verdict and CI at the exact head, the base chain, stacked children and the merge plan. |
Code and GitHub reads
| Method | Route | Purpose |
|---|---|---|
| GET | /code/roots, /code/outline, /code/files, /code/read | Browse and read the registered repositories. |
| POST | /code/search | Search code with a pattern. This is a POST because patterns do not fit a query string well. |
| GET | /github/:owner/:repo/prs | The repository's pull requests. |
| GET | /github/:owner/:repo/prs/:number/diff, /comments, /checks | The diff, the comments and the checks for one PR. |
| POST | /github/overlap | Run one duplicate-work pass. It is a dry run unless CONDENSATE_PR_OVERLAP=on. |
Completions endpoint
POST /v1/chat/completions and GET /v1/models expose an OpenAI-compatible completions endpoint. Each call is one model call. It runs on one of the workspace's accounts, and fails over to another account if the first one refuses.
A completions call is not an agent thread. It has no tools and no durable multi-turn state. For agent work, use POST /spawn.
Each call writes one completion event to the workspace's completions thread, so the usage is recorded there.
| Header | Purpose |
|---|---|
x-condensate-workspace | The workspace the call is charged to. Required, unless the host sets CONDENSATE_COMPLETIONS_DEFAULT_WORKSPACE. |
x-condensate-session | An optional session label, up to 128 characters. |
x-condensate-traffic | work (the default) or smoke. |
Set stream: true in the body to receive server-sent deltas. Image content is not supported in this version. GET /v1/models lists the models the endpoint can route, without the deprecated ones.
Errors use OpenAI's shape, { "error": { "message", "type", "code" } }. Codes include unknown_workspace (400), model_not_found (404), no_eligible_account and no_spendable_account (409), accounts_exhausted (429) and rate_limited (429, with Retry-After when the provider gave a wait).
Operating the host
| Method | Route | Purpose |
|---|---|---|
| GET | /health | The build commit, the fields /spawn accepts, and any open memory alert. |
| GET | /live | Live threads, and any open account-pool exhaustion episodes. |
| GET | /limits | The build seat limit, read from the hub. |
| GET | /host-load | Load averages, CPU count and the booted iOS Simulators on the host. |
| GET | /timings | Per-request timings. |
| GET | /metrics, /metrics/history, /metrics/estate, /metrics/keeper, /metrics/cost-per-merged-pr | Runtime metrics. |
| GET, POST, DELETE | /drain | Read, arm or disarm a drain for a restart. /drain/claim manages claims. |
| GET | /keeper/spawn-pause, POST /keeper/spawn-pause/clear | Read or clear the spawn pause. |
| GET | /attention, /attention/changes, /attention/follow, /attention/:id | Items that need a person. |
| GET | /incidents | Failed-turn incidents. |
| GET | /peers, POST /peers/external, DELETE /peers/external/:name | Peers, and external peers that record threads without a local engine. |
| POST | /previews, GET /previews, DELETE /previews/:id | Local server previews. |
Account routes under /accounts are covered in Accounts.
Some operator routes check the Host and Origin headers and refuse callers that are not local. These include the Codex reset-credit route and the model-refusal clear.
During a drain or a spawn pause, new threads are refused with a 503 and a Retry-After header. Running turns continue. A draining response reports how many threads are still mid-turn.