Skip to content

Latest commit

 

History

History
320 lines (271 loc) · 32.6 KB

http-api.md

File metadata and controls

320 lines (271 loc) · 32.6 KB

HTTP API guide

Preview. Describes the P6 runtime on main as of 2026-11-12. The machine-readable contracts are docs/api/openapi.yaml (control plane) and docs/api/harness-openapi.yaml (data plane); this page explains how they fit together and records behaviour the specs do not. Workload routes are covered in docs/context-service.md.

Two APIs

API Who calls it Found via What it does
Control plane Users, mocactl Its own URL (SH_CONTROL_PLANE_URL for mocactl) Login, sessions, credentials, config bundles, token minting
Data plane (harness) Clients holding a session token GET /v1/discovery on the control plane (harnessUrl) Turns, leaf runs, attach, cancel

A client logs in, creates a session (POST /v1/sessions returns {sessionId, token, expiresAt}), and sends turns to the harness with that session token. A session token has scope turn:write, a 5-minute default TTL (SH_SESSION_TOKEN_TTL_SECONDS), and is bound to one session; POST /v1/sessions/{id}/token mints a new one. API tokens (scope api, 15-minute default TTL via SH_API_TOKEN_TTL_SECONDS, refreshable) are for the control plane and the harness's /workloads/* routes; they are never accepted on /turn.

The same handler runs on every deployment path (VM, Kubernetes, Compose), so the data-plane routes below are identical on all of them.

Authentication on the data plane

Send Authorization: Bearer <session token>. The token is an Ed25519 JWT checked against SH_SESSION_TOKEN_PUBLIC_KEYS.

  • No token: 401 token_required when SH_REQUIRE_AUTH=true; otherwise the call is anonymous and uses the deployment's ambient model credential (the Compose default).
  • A present but bad token is refused in either mode (token_invalid, token_expired).
  • A token for one session cannot drive another: a sessionId in the body that differs from the token's session gives 400 session_mismatch; an X-SH-Subject that differs from the token's subject gives 400 subject_conflict.
  • For authenticated turns the harness exchanges the token with the control plane for the user's inference credential, the config bundle (configRef) and the sandbox tier. On /turn these always come from the control plane, never from the request. /v1/runs is different: it does not inherit the session's bundle, and a leaf takes its configRef from the envelope (see Leaf envelope and result).
  • An unreachable control plane fails the turn with 503 credential_unavailable; it never falls back to the environment.

Routes

Route Auth Purpose
GET /health none Liveness: 200 ok, header X-Moca-Version
POST /v1/turn (alias POST /turn) session token One interactive turn
GET /v1/turn?sessionId= session token Attach to a running or finished detachable turn
POST /v1/turn/cancel session token Cancel a detachable turn
POST /v1/runs (alias POST /runs) session token Run a leaf to completion
GET /runs/status?sessionId= session token Read a leaf's stored result
POST /run-leaf, GET /run-leaf/status session token Deprecated aliases of /runs and /runs/status; log a warning once per process

The unprefixed POST /turn and POST /runs are supported, frozen aliases of the /v1 routes: the same handler, so the same auth, body and responses, with no removal date (change policy, decision 3). New features appear under /v1 only, so the detachable-turn routes have no unprefixed form; a new client should use /v1. docs/api/harness-openapi.yaml describes both aliases.

Matching is by URL and not uniform. /health, /turn, /v1/turn (POST), /v1/turn/cancel, /runs, /v1/runs and /run-leaf match the exact URL, so a query string defeats them. GET /v1/turn requires and accepts a query string, /runs/status and /run-leaf/status match by prefix, and /workloads strips the query. Any other path returns an empty 404. The supervisor admin port (/healthz, /readyz, /metrics) is separate and loopback by default.

POST /v1/turn

curl -s -H 'Content-Type: application/json' \
  -d '{"prompt":"Run uname -a and tell me the kernel."}' \
  http://127.0.0.1:8080/turn
Field Type Required Notes
prompt string yes Missing gives 400 prompt_required
sessionId string no Authenticated: defaults to the token's session, created if absent. Anonymous: must exist (404 otherwise); omit it to create one
detachable boolean no true is honored only with SH_TURN_DETACH=1, a valid token, and Accept: text/event-stream; otherwise ignored

Sync response (200): {sessionId, response, stopReason, errorMessage?, usage?: {input, output, cacheRead, cacheWrite, total}, sandbox?: {id, tier, workspaceReset?: {from, reason}}}. A model-level failure still returns 200 with stopReason error or aborted and an errorMessage.

Streaming: send Accept: text/event-stream and read server-sent events (below).

Errors before any output:

Status Body error Meaning
400 read_error, invalid_json, prompt_required, session_mismatch, subject_conflict Bad request
401 token_required, token_invalid, token_expired Auth
404 session_not_found A session that does not exist (anonymous calls), or passed through from the credential exchange
409 turn_in_progress SH_TURN_DETACH=1 and a detachable turn is live (authenticated callers also get turnId)
410 config_bundle_not_found The session's config bundle is missing or expired; the turn never runs without its skills
503 sandbox_unavailable Sandbox pool saturated, empty, or the session's sandbox is pending (affinity). Has Retry-After, and a message naming the cause (a pool, tier, template or sandbox id; for a host's mid-turn refusal a fixed sentence, never the host's figures)
503 credential_unavailable, redis_unavailable Control plane or Redis fault. Has Retry-After for 503s
500 internal_error Never carries error text

Error bodies are {error, sessionId?}, plus a message on auth errors, on the /turn 503 sandbox_unavailable and on the /runs 501, and turnId on turn_in_progress. The 503 Retry-After is KAGENTI_SYNC_SATURATION_RETRY_AFTER_S (default 5), or, for a pending affinity, the wait clamped to 1 to 10 seconds. The credential exchange also passes through credential_required, credential_ambiguous, credential_not_found, endpoint_unresolved, session_not_found, token_invalid and token_expired, so authenticated callers can receive them too; any other non-200 answer from it becomes 503 credential_unavailable.

Overload. Before hand-off, the supervisor refuses a connection with a raw HTTP/1.1 429, Retry-After: 1 and {"error":"overloaded"}. This is a transport-level answer to any route and is not in the OpenAPI files.

Streaming frames

SSE framing is [id: <turnId>:<entryId>\n]event: <type>\ndata: <frame JSON>\n\n. A comment : keepalive is sent every SH_TURN_STREAM_KEEPALIVE_MS (default 20000) so proxies keep the connection. Headers: Content-Type: text/event-stream, Cache-Control: no-cache, X-Accel-Buffering: no.

Headers go out with the first frame. If none has been written after SH_TURN_STREAM_FIRST_FRAME_FLUSH_MS (default 15000, 0 disables), they go out anyway with a : keepalive comment (a detachable turn writes its turn frame instead), so a proxy idle timeout cannot cut a slow first frame. A failure after that point is a terminal error frame, not an HTTP status.

Event Fields Notes
turn turnId, sessionId, truncated?, ended? Detachable and attach only; not terminal
text delta
thinking delta May never fire
tool_use id, name, args
tool_result id, isError, preview Preview is clipped to SH_TURN_STREAM_TOOL_RESULT_PREVIEW_BYTES (2048)
workspace_reset sessionId, from, tier, reason First, when the sandbox changed since the last turn (detached or retiered)
done sessionId, stopReason, usage? Terminal
error sessionId, stopReason, errorMessage?, usage?, abortReason? Terminal. abortReason: cancelled, unwatched, restarting, lease_lost, owner_lost

done is used when stopReason is stop, length, end_turn or max_tokens; anything else ends in error. On a non-detachable stream a client disconnect aborts the turn.

A terminal error frame for a host's mid-turn capacity refusal has the 503 message's fixed sentence as its errorMessage, never the host's figures. The refused command's tool_result is a tool result like any other: its preview is the clipped text the tool returned, which for a refusal is the transport's error text.

Detachable turns: attach and cancel

With SH_TURN_DETACH=1, a turn started with detachable: true outlives its connection. Every logged frame carries an id:; a frame whose log write failed has none.

  • GET /v1/turn?sessionId=ID follows the live turn and replays from the log. Send Last-Event-ID: <turnId>:<entryId> to resume after that entry; if the cursor is older than the retained log the turn frame has truncated: true. If the cursor is at or past the end of a finished turn, the stream is a single turn frame with ended: true; on a running turn it keeps following live from the tail. Errors: 400 sessionId_required, 401, 404 turn_not_found (including when detach is off), 503 redis_unavailable. If the owning process is gone the stream ends with an error frame, abortReason: owner_lost.
  • POST /v1/turn/cancel with {sessionId, turnId?} returns 202 {turnId, outcome}, where outcome is requested or ended (a no-op). 409 turn_mismatch if turnId names a different turn; 404 turn_not_found.
  • An unwatched turn is aborted after SH_TURN_DETACHED_MAX_S (default 1800); a finished turn stays replayable for SH_TURN_LOG_TTL_S (default 86400).

POST /v1/runs

Runs one leaf to completion and returns its result. The request is the leaf envelope and the response is the leaf result; both are specified in Leaf envelope and result.

  • 400 envelope_invalid for a body that is not a leaf, solve or prompt envelope; 400 configRef_invalid for a non-string configRef.
  • GET /runs/status?sessionId=ID returns the stored result: {status: "queued"} until one exists (also for a session that never existed), then the result for that status. 400 sessionId_required.
  • An authenticated caller may not pass tenant (400 tenant_not_allowed).
  • async: true is removed, and stays removed. It returns 400 async_removed: the KEDA drainer that consumed the queue went with the Knative/KEDA path (ADR-0041). This route is not coming back — it is unauthenticated when SH_REQUIRE_AUTH is off, which would be a second trust model for one queue. Its replacement is the authenticated, owner-scoped POST /v1/sessions/{id}/turns with async: true → 202 {sessionId, turnId}, designed in ADR-0047 and documented in docs/api/openapi.yaml. That path works, on one condition: each worker needs SH_ASYNC_DRAIN=1 (off by default) to drain the queue. Under MOCA_TENANCY=multi the dequeue hands the worker grants instead of a key, so the control plane needs the grant ring and the inference listener configured — it refuses to boot without them. Poll GET /v1/sessions/{id}/turns/{turnId} for state and result. That body is bounded: the turn's output is not inlined, because the route is polled — result.summary is one clipped line (MOCA_TURN_SUMMARY_BYTES, default 2048, which also caps result.verdict.reason and the gate's two lines, the body's other model-written strings), result.workspace describes the patch (baseline, sha256, size, diffstat) and result.artifacts names what GET /v1/sessions/{id}/turns/{turnId}/artifacts/patch will serve whole, with an ETag. See dispatch archetypes for the operator steps.
  • On a saturated pool the sync path waits with backoff (up to KAGENTI_SYNC_SATURATION_WAIT_MS, 30 s) and then returns 503 with Retry-After and {"status":"failed","reason":"saturated"}.

Control plane

The control-plane routes are listed in docs/api/openapi.yaml. In outline:

Area Routes
Probes GET /healthz, GET /readyz, GET /v1/discovery (harness URL, sandbox tiers, version; no auth)
Login POST /v1/auth/device, /v1/auth/device/token, /v1/auth/token (refresh), /v1/auth/revoke, /v1/auth/revoke-all, GET /v1/me
Sessions POST and GET /v1/sessions, GET, PATCH and DELETE /v1/sessions/{id}, GET /v1/sessions/{id}/resources, POST /v1/sessions/{id}/token
Async turns POST /v1/sessions/{id}/turns (submit, 202), GET /v1/sessions/{id}/turns/{turnId} (state, attempts, bounded result), GET …/turns/{turnId}/artifacts/{kind} (the patch, whole), DELETE the turn path (cancel while queued)
Models GET /v1/models?credential= (the models a credential's endpoint lists), GET /v1/sessions/{id}/models (the models the session's credential lists)
Credentials GET /v1/credentials, PUT and DELETE /v1/credentials/{name}
Config bundles POST and GET /v1/config-bundles (your own, newest first), DELETE /v1/config-bundles/{digest}
Internal POST /internal/credentials (session token → credential) and POST /internal/turn-credentials (queued turn id → credential, at dequeue): data plane only, both authenticated with SH_EXCHANGE_TOKEN
Templates GET /v1/templates, GET /v1/templates/{id}, GET /v1/templates/{id}/builds[/{build}], GET /v1/templates/{id}/tags: both route profiles (API 1.4.0)
Self-serve POST /v1/templates, POST /v1/templates/{id}/builds, POST /v1/templates/{id}/builds/{build}/cancel, GET and PUT /v1/policy, GET /v1/quota: both route profiles (API 1.5.0)
Template admin POST /v1/templates/{id}/tags, DELETE /v1/templates/{id}/tags/{tag}, PATCH /v1/templates/{id} (the owner, or an admin), PUT /v1/templates/{id}/owner (an admin): both route profiles (API 1.8.0)
Host agents POST /v1/hosts/{host}/inventory, /builds/claim, /builds/{build}/log and /report, GET /v1/hosts/{host}/blobs/{digest}: a host's own bearer, both route profiles (API 1.10.0)
Activation POST /v1/templates/{id}/activate and /deactivate (both route profiles); GET /v1/hosts/{host}/wanted, POST /v1/hosts/{host}/workers/report (a host's own bearer) (API 1.11.0)
Egress records GET /v1/sandboxes/{id}/egress (the owner or an admin; sandbox profile); POST /v1/hosts/{host}/egress (a host's own bearer) (API 1.14.0)
Retire POST /v1/templates/{id}/retire, DELETE /v1/templates/{id}/builds/{build}: both route profiles (API 1.18.0)
Subjects GET /v1/subjects; PUT, DELETE /v1/subjects/{subject}[/roles/admin] (enroll, unenroll; grant with an optional until, revoke): both route profiles (API 1.20.0)
Admin PUT /v1/quota/{subject|default}, POST /v1/templates/{id}/builds/{build}/reject: admins, both route profiles (API 1.21.0)

POST /v1/sessions takes an optional model, and PATCH /v1/sessions/{id} with {"model": ID} switches it (null returns the session to the deployment default). A turn already running keeps its model; the next turn uses the new one. An async turn is the exception, and it is not a next turn either: a turn already queued keeps the model it was submitted with, however long it waits, because the turn record pins model and sandboxTier at submission and /internal/turn-credentials reads them from the record (#388). The switch applies to turns submitted after it. The id is checked against the credential's catalog (400 model_unavailable when it is not listed); when the endpoint cannot list its models, the id is accepted unverified and the answer has modelVerified: false. Only the two list routes answer 503 model_catalog_unavailable. These routes came with API 1.1.0; see the changelog.

The template read routes came with API 1.4.0 and mount on both route profiles, so a session's brain and a sandbox client read the same templates. With SH_PROVENANCE_DIR set, templates live in the control plane's template store (SH_SANDBOX_TEMPLATES is imported into it once); unset, they come from the env list at every start. Each template is a name over its builds, with tags naming builds (default is what a bare id names), and each registered build reports its readiness from the relay's presence: active, inactive, or unknown when presence cannot be read. A sandbox create names id, id:tag or id@<build id>, resolved to one build at creation and kept for the sandbox's life (the Sandbox shows buildId). A private template, like an unknown id or build, answers 404 template_not_found to anyone but its owner and admins. See the template lifecycle spec.

The self-serve routes came with API 1.5.0 and need SH_PROVENANCE_DIR. An enrolled client creates a template from an image pinned by digest; the deployment's policy (GET /v1/policy, set by an admin with PUT) checks it before anything is queued, and a refusal is 422 policy_refused naming the gating rule (GATING-RULES.md). Ids are unique per deployment (409 template_exists); quotas are per subject (429 quota_exceeded naming which; GET /v1/quota shows them). A create with the same inputs as a build of the caller's own template answers that build, reused: true.

The template admin routes came with API 1.8.0 and need SH_PROVENANCE_DIR. A template's owner, or an admin, moves tags onto a registered build (id:tag, and the bare id for default, then name it for new sandboxes and sessions; those already created keep their build), removes a tag (never default; the build stays), and changes the description or the visibility (private hides it from other subjects, as a 404). An admin transfers a template to another enrolled subject (github:<id> or oidc:<sub>), including one the deployment declared, which has no owner until then. Each change is a provenance record (tag, visibility or owner) naming the new value and the one before. The host routes came with API 1.10.0. A KVM host's agent (deploy/sbx/host-agent.sh) claims queued builds, builds them with template-build.sh and reports them, with its own bearer (SH_TEMPLATE_HOSTS, SH_HOST_TOKEN_<ID>); the control plane registers a built build or rejects it, by policy, naming the rule. A client follows its build by the create's handle through queued, building, probing and registered (or failed with reason.step, rejected with reason.rule).

Activation came with API 1.11.0. A client takes or renews a lease on a registered build (activate, 60 s to a day a grant, renewals unlimited); a build is wanted running only while a lease stands, and the host agents start and stop the installed workers by each host's wanted state. A build no host holds is 409 template_unavailable; one whose holders are all at their active limit with leased builds is 409 no_active_slot with Retry-After; over the subject's active quota is 429 quota_exceeded. With template hosts configured, a sandbox create on a build that is not active takes the caller's lease and answers 409 template_not_active with Retry-After (activate: false starts nothing). A template imported from SH_SANDBOX_TEMPLATES is never gated (the deployment runs its worker) and takes no lease.

Egress records came with API 1.14.0. A sandbox's egress log (GET /v1/sandboxes/{id}/egress) holds the KVM host's egress proxy events for it, shipped by the host agent; the sandbox's end record names the log's sha256. Paths are logged without query, fragment or userinfo, and an injected credential appears by name only, but a secret a guest puts in a URL path segment is logged as sent. See the egress records spec.

Retire came with API 1.18.0. The template's owner, or an admin, retires a whole template (POST /v1/templates/{id}/retire, with an optional reason) or one build (DELETE /v1/templates/{id}/builds/{build}). A retired build's leases go and its holding hosts are told to stop its worker; it is never served again: a sandbox create or an activation naming it, a tag of it or a template whose every build is retired is 410 template_retired. A retire is refused 409 build_in_use while a live sandbox runs on the build, and is idempotent. Each build retired writes a retire record naming the caller, the status before and the build's build record. A retire cannot be undone: a new build of the template is the way back. Each build lists heldBy, the hosts still holding its snapshot, and a retired build reports capacity while its worker still runs (null once its host has stopped it). Since API 1.19.0 (#743) each holding host's agent then removes the build's worker and snapshot (the wanted state's remove) and reports it, a retire record by host:<id> with event: removed, and heldBy drops the host. mocactl sbx templates retire --wait waits for the stop and for heldBy to empty, and returns at once for a build no host holds (heldBy null or empty: no host agent stops its worker) and for a shared one (its snapshot or worker serves a build neither retired nor rejected, so its worker is kept running for that build).

Who is enrolled and who is an admin (API 1.20.0, with a template store): the deployment's settings (SH_ALLOWED_SUBJECTS, SH_ADMIN_SUBJECTS) are the bootstrap, and admins add to them through /v1/subjects: any admin reads the list, only an admin named in SH_ADMIN_SUBJECTS changes it. Roles and enrollment are evaluated per request, so a grant, a revoke or a lapsed until takes effect at the subject's next request; a token's roles claim reports what held when it was minted. A subject is github:<numeric id> or oidc:<provider sub>, never test:<n>. See the enrollment and roles spec.

The admin routes came with API 1.21.0. An admin sets the deployment default quota (PUT /v1/quota/default) or one subject's override (PUT /v1/quota/{subject}, github:<numeric id> or oidc:<provider sub>; a body of null removes it). A quota holds templates, buildsQueued, active and, optionally, owned (a write without owned keeps the target's; a subject whose override has none has the default's). Overrides live in the policy (quotaBySubject), so each change is a policy record naming the admin, enforced at once; ?expect= (the value read, as JSON percent-encoded into the query, e.g. ?expect=%7B%22templates%22%3A3%2C%22buildsQueued%22%3A1%2C%22active%22%3A1%7D, or ?expect=null for no override) makes it a compare-and-set on the four counters, 409 quota_changed with nothing written when the quota is no longer that value. A PUT /v1/policy stores the whole policy, overrides included: with ?expect= (the digest that GET /v1/policy answered) it is refused 409 policy_changed, nothing written and the body's digest the policy's now, if anything changed since that read; without it, it replaces the policy as sent. GET /v1/quota shows the limits that apply to the caller, quotaSource (subject or default) and ownedSource, the same for owned alone. An admin also rejects a registered build after the fact (POST /v1/templates/{id}/builds/{build}/reject {reason}): it becomes rejected (reason.rule: admin), its leases go and its holding hosts are told to stop its worker, as for a retire (but not to remove it), and a sandbox create naming it is 400 unknown_template. A reject record names the admin, the reason and the build's build record; a reject is refused 409 build_in_use under a live sandbox, is idempotent, and cannot be undone. mocactl sbx templates quota TARGET sets a quota from the terminal (--owned N for owned). A quota write without owned keeps the target's current owned, so to return one subject's owned to the default, remove its override (--clear, or a body of null) and then set its quota again.

Another user's session returns 404, not 403. Control-plane error codes and statuses: 400 (invalid_json, invalid_request, invalid_grant, subject_conflict, session_mismatch, digest_mismatch, configRef_invalid, credential_required, credential_ambiguous, endpoint_unresolved, model_unavailable), 401 (token_required, token_invalid, token_expired, unauthorized), 403 forbidden, 404 (session_not_found, config_bundle_not_found, credential_not_found, template_not_found, turn_not_found), 409 (template_exists, turn_not_cancellable, turn_not_claimable, no_active_slot, template_unavailable, template_not_active, build_in_use, bootstrap_subject, self_revoke, admin_granted, quota_changed, policy_changed), 410 (device_code_expired, template_retired), 422 policy_refused, 428 authorization_pending, 429 (quota_exceeded, bundle_quota_exceeded, async_quota_exhausted), 500 internal_error, 501 workload_runs_unavailable, 502 identity_provider_misconfigured, 503 (credential_unavailable, redis_unavailable, model_catalog_unavailable). The list may not be complete; the mapping is in packages/control-plane/src/errors.ts.

Note that the same config_bundle_not_found is 404 on the control plane and 410 on the harness.

Known gaps

  • The supervisor's 429 overloaded answer is not in docs/api/harness-openapi.yaml.
  • harness-openapi.yaml describes /runs/status as for an async run; sync runs are stored and pollable too.
  • prompt is only checked for presence; how a non-string behaves is not specified.