Reference
The interactive reference and the raw spec are the source of truth — this page links to both and adds what a schema alone doesn’t carry: a quick operation index and error codes.
- Interactive reference — every operation, every schema, try-it-out against your own deployment.
- Raw OpenAPI document — the same spec as JSON.
Both links are root-relative and work identically whether you’re reading
this page from the app host’s /docs prefix or a dedicated docs host’s own
root (see Run your own) — both hosts serve /api/docs and
/api/openapi.json.
The spec covers the worker- and dispatcher-facing surface this guide walks through in prose: turns, the worker registry, and the hub’s own review and work-run queues. It does not cover the browser/UI surface (sessions, roots, search, the worker registry’s browser-facing half) — that surface is documented in Integrate as a UI instead, by design: it’s session-cookie gated, not a service contract meant for machine-to-machine consumption the way an OpenAPI document implies.
Every operation
| Group | Method | Path | Scope | Purpose |
|---|---|---|---|---|
| Capabilities | POST | / | agent:report | Reports what a root’s harness can currently do — tools, MCP servers, skills, commands, and subagents — replacing any prior report for the same root_id. |
| Index | GET | / | agent:report | Per-native_id [fingerprint, message_count] pairs for one root — what a worker diffs its own local sessions against before deciding what POST /api/agent/index/sessions needs to publish. |
| Index | POST | / | agent:report | One publish batch of sessions — the write path a worker calls after diffing its own sessions against GET /api/agent/index/fingerprints. |
| Integrations | POST | / | review:run | Queues one read-only idea-review turn, idempotently re-reporting an identical resubmission under the same request_id. |
| Integrations | GET | / | review:run | Polls the state of a previously queued idea-review turn. |
| Integrations | POST | / | work:run | Queues one service work run against a hub-configured work profile, idempotently re-reporting an identical resubmission under the same request_id. |
| Integrations | GET | / | work:run | Polls a queued or completed service work run, including the state of its own result callback to WORK_REPORT_URL. |
| Jobs | GET | / | agent:claim | Claims one pending generic job for the polling worker, or 204 when none is ready for the given roots. |
| Jobs | POST | / | agent:report | Reports the terminal outcome of a claimed job. |
| Turns | GET | / | agent:report | Reads the reservation the calling worker belongs to. |
| Turns | GET | / | agent:report | Lists turns, newest-first, optionally filtered by status. |
| Turns | GET | / | agent:claim | Claims one pending execution turn for the polling worker, or 204 when none is ready. |
| Turns | POST | / | agent:report | Reports success, failure, an ordinary capped requeue, or an uncapped parked requeue when park_until_ms is supplied. |
| Turns | POST | / | agent:report | Appends one batch of events to a claimed turn’s stream. |
| Turns | GET | / | agent:report | Every recorded state transition for one turn, oldest-first (pending → claimed → done/expired, including any reclaims/requeues in between). |
| Turns | GET | / | agent:claim | Waits for new claimable work, or for the caller’s reservation to end. |
| Workers | POST | / | execution:control | Claims one pending control command for this principal’s resolved self instance, or 204 when none is pending. |
| Workers | GET | / | execution:control | Reads a one-time code exactly once. |
| Workers | POST | / | execution:control | Reports the terminal outcome of a provider-auth-control command. |
| Workers | POST | / | execution:control | Reports progress for a claimed provider-auth-control command. |
| Workers | POST | / | execution:control | Renews a provider-auth-control command’s lease. |
| Workers | PUT | / | execution:heartbeat | Upserts this principal’s worker-registry row. |
| enrollment | POST | / | — | Enrolls a freshly provisioned worker against its reservation. |
| enrollment | POST | / | — | A static-pool machine collects the enrollment token of its assigned reservation. |
| issuer | GET | / | — | The Ed25519 public keys a provisioner verifies the hub’s signed webhooks against (Standard Webhooks v1a). |
| issuer | GET | / | — | The public keys that verify tokens this hub issued: the active key, any key published ahead of activation, and retiring keys. |
| issuer | GET | / | — | The same document as /.well-known/openid-configuration, for RFC 8414 clients. |
| issuer | GET | / | — | The workload issuer’s OpenID Connect discovery document. |
| issuer | GET | / | — | Always refused: this issuer only supports the client credentials grant. |
| issuer | POST | / | — | Exchanges client credentials for a short-lived access token for one resource. |
| provisioning | POST | / | workers:provision:{pool} | Fetches the single-use enrollment token for a reservation. |
| provisioning | POST | / | workers:provision:{pool} | Reports a provisioning status change. |
| relay | GET | / | — | The Ed25519 public keys (JWKS) that verify relay tickets. |
| relay | POST | / | relay:audit | Stores a batch of relay audit events. |
| relay | GET | / | relay:sync | The append-only revocation log after a cursor, 500 entries per page. |
| relay | POST | / | relay:sync | Revokes a relay session the relay logged out. |
| relay | POST | / | relay:open | Mints a short-lived bearer ticket for opening a worker service through the relay. |
| remote | GET | / | — | Names the issuer, token resource and scopes a client needs. |
| remote | POST | / | chat:drive | Starts a new chat on a root, idempotently per request_id. |
| remote | GET | / | chat:read | Lists machines, their roots and whether each is online, plus the known harnesses. |
| remote | GET | / | chat:read | Lists a root’s project directories with session counts. |
| remote | GET | / | chat:read | Searches message text across sessions. |
| remote | GET | / | chat:read | Lists sessions. |
| remote | GET | / | chat:read | Fetches one session. |
| remote | GET | / | chat:read | Reads a page of a session’s messages, newest first. |
| remote | POST | / | chat:drive | Queues a message as a session’s next turn, idempotently per request_id. |
| remote | GET | / | chat:read | Reads (and long-polls) a turn’s events. |
| reservations | GET | / | workers:reserve | Lists the caller’s reservations, newest first, at most 200. |
| reservations | POST | / | workers:reserve | Requests an ephemeral worker from a pool. |
| reservations | GET | / | workers:reserve | Reads one of the caller’s reservations. |
| reservations | DELETE | / | workers:reserve | Cancels or releases a reservation. |
| reservations | POST | / | chat:drive, workers:reserve | Moves a session to an active reservation. |
| workers-admin | GET | / | workers:admin | Lists pools. |
| workers-admin | GET | / | workers:admin | Reads a pool document with its version. |
| workers-admin | PUT | / | workers:admin | Creates or replaces a pool (GitOps style: the whole document, optimistic version). |
| workers-admin | DELETE | / | workers:admin | Retires a pool: no new reservations, existing ones run to their end. |
| workers-admin | POST | / | workers:admin | Ends everything a departed principal holds: reservations, workers, pending turns and tokens. |
| workers-admin | POST | / | workers:admin | Lifts a deprovisioning so the principal can reserve workers again. |
| workers-admin | GET | / | workers:admin | Lists the issuer’s clients (never their secrets). |
| workers-admin | POST | / | workers:admin | Registers a service or static-machine client of the workload issuer. |
| workers-admin | POST | / | workers:admin | Disables a client and revokes every token it holds. |
| workers-admin | POST | / | workers:admin | Replaces a service client’s secret; the old one stops working at once. |
| workers-admin | POST | / | workers:admin | Rotates the issuer’s signing key: the staged next key becomes active and a new one is staged. |
| workers-admin | GET | / | workers:admin | Every alias set, rename and remove, newest first. |
| workers-admin | PUT | / | workers:admin | Gives a bound machine an alias (a display and input name; the id never changes). |
| workers-admin | DELETE | / | workers:admin | Removes an alias. |
| workers-admin | POST | / | workers:admin | Renames an alias. |
| workers-admin | GET | / | workers:admin | Lists every machine place the hub holds a binding, alias or conflict for. |
| workers-admin | GET | / | workers:admin | Resolves a machine id, name or alias to its canonical place. |
| workers-admin | PUT | / | workers:admin | Binds a machine name to an enrolled identity (the operator override of first-report binding). |
| workers-admin | DELETE | / | workers:admin | Forgets a machine name’s binding and its conflicts; the next report binds it again. |
| workers-admin | PUT | / | workers:admin | Registers or updates a machine of a static pool. |
| workers-admin | POST | / | workers:admin | Marks a machine that needed a reset as clean and available again. |
| workers-admin | PUT | / | workers:admin | Rebinds an ordinary root to a principal (the operator override of first-come binding). |
| workers-admin | PUT | / | workers:admin | Assigns a principal to a team, which the pool limits and budgets count against. |
| workers-admin | DELETE | / | workers:admin | Removes a principal’s team assignment, and with it any pool access the team gave. |
76 operations, generated from the OpenAPI document.
Error codes
| Status | Meaning |
|---|---|
400 | A field fails validation, a request isn’t valid JSON, or a semantically invalid combination (e.g. neither provider nor tier given on turn creation). |
401 | Missing or invalid credential. See Authentication. |
403 | Valid credential, insufficient scope, or (on either integration queue) a non-service-principal subject. |
404 | The referenced turn, session, or job doesn’t exist — or, for either the review queue or the work-run queue, that neither is configured on this hub at all (checked before authentication, so this is the response with or without a token, independently for each of the two). |
409 | A fencing conflict (claim_token/claim_generation mismatch) or a reused batch_id with a different payload — or, once a turn/command is already terminal, one of two different rules depending on the write: an events/progress write against it is 409 for EVERYONE, including its own winning claimant (the stream is closed, permanently); a completion write (done/complete) against it is 409 for anyone except an exact retry from its winning claimant, which stays a 200 no-op instead. On the review queue’s or the work-run queue’s own creation route, 409 also covers the same request_id resubmitted with different input. |
413 | Request body over the route’s size cap. |
415 | Missing or non-JSON Content-Type where a route requires one. |
422 | Syntactically valid JSON that doesn’t match the expected request shape. |
500 | Internal error. |
503 | Two unrelated causes, telling apart which surface you’re on: on the worker-facing routes, agent authentication isn’t configured on this hub at all, and every one of them answers this unconditionally with no auth check performed; on the review queue’s or the work-run queue’s own creation route specifically, it means authentication already succeeded but no worker on this hub could ever execute the resulting turn/run (see Integrate as a dispatcher and Run work through the hub: work runs). |
Body shape. An application-level or authentication error is JSON,
{"error": "<message>"}. The one exception is a body-decoding failure
(bad JSON syntax, a wrong Content-Type, or a body that doesn’t match the
expected shape) on most worker-facing write routes: that class of failure
answers with a plain-text body instead of JSON, before any
application-level check runs — the review and work-run creation routes are
the write routes that stay JSON even for a malformed body. The
operation table above doesn’t carry per-status body types; the
interactive reference and the raw spec do, declaring
text/plain explicitly on exactly the status codes this affects,
operation by operation.
Versioning
The spec carries a single version string covering the whole surface as one unit — there’s no per-operation versioning. Additive changes (a new operation, a new optional field, a widened response type) ship without notice; a breaking change bumps the spec’s own version. Re-read the spec whenever you upgrade against a new one.