Skip to content

HTTP reference

Submit an action, then read its record for progress and results. The service saves accepted work before execution and uses the same requests and results as the CLI. When connecting a platform webhook, verify its signature and translate its payload to the request below before submitting it.

Authorization and admission

When LANDING_TOKEN is configured, action endpoints require Authorization: Bearer TOKEN. JSON admission requires a JSON Content-Type such as application/json, has a 16 MiB limit, and rejects unknown fields.

{
  "mode": "gatekeeper",
  "instruction": "Review the candidate against these acceptance criteria.",
  "workspace": "candidate",
  "input": [
    {"type": "text", "text": "Missing arguments must exit 2."},
    {"type": "file", "name": "check.log", "media_type": "text/plain", "content": "Acceptance passed.\n"}
  ],
  "checks": ["make acceptance"]
}
Field Contract
mode Required: issuer, fixer, gatekeeper, explainer, or bumper.
instruction Optional string; a nonblank instruction or nonempty input is required.
workspace Registered name, default default; the service prepares no checkout.
input Text or file snapshots, default empty; files require name and content, with media_type defaulting to text/plain.
checks Nonblank commands, default empty; supported only by fixer, gatekeeper, and bumper. Fixer and bumper run checks after edits; gatekeeper runs them before evaluation.

POST /v1/actions commits the request before returning 201 with an action record and Location. Optional Idempotency-Key accepts 1–256 characters. The same key and request return the existing action with 200; conflicting content returns 409. Retry admission also supports the header.

Resources

Method and path Contract
POST /v1/actions Admit work.
GET /v1/actions?limit=50&cursor=act_example History, newest first.
GET /v1/actions/{id} Action record.
GET /v1/actions/{id}/events?after=0&limit=50 Lifecycle, validation, and publication events.
POST /v1/actions/{id}/cancellation Request cancellation.
POST /v1/actions/{id}/retries Retry a terminal action's original request.
GET /healthz HTTP liveness.
GET /up Worker and SQLite readiness.
GET /docs Scalar API reference with interactive requests and bearer authentication.
GET /openapi.json Generated schema.

Health checks, /docs, and the generated schema are public. Documentation describes the API without exposing task history or credentials.

Collections are arrays. limit is 1–100, default 50. Follow Link: rel="next" for pagination. Action cursors are IDs; event after uses the last numeric event ID, default 0. LANDING_BASE_URL supplies the public origin behind a proxy.

Action records

Field Contract
id, mode, instruction, workspace Identity and delegated work; IDs are opaque.
status Execution status: queued, running, completed, failed, cancelled, or interrupted.
result Text or null; failed actions can retain an answer.
decision Gatekeeper recommendation: allow, block, or inconclusive; null for other modes. A missing gatekeeper decision is inconclusive.
error Error details or null.
retry_of Original action ID or null.
created_at, updated_at Record timestamps.
started_at, completed_at, cancel_requested_at Lifecycle timestamps or null.

Read the record when needed; terminal states are completed, failed, cancelled, and interrupted. Admission does not wait for completion, and caller disconnection does not cancel accepted work. Events contain id, type, created_at, and data. Validation events record command, output, exit code, and timeout status.

Cancellation returns 202 while active work stops, otherwise 200 for terminal work. Retry requires a terminal action and preserves workspace edits. After worker restart, active work becomes interrupted, queued work resumes, and completed work does not replay.

Errors

Errors use FastAPI's JSON responses with a detail field. Request validation returns 422 with a list of field errors; HTTP errors return a message:

{
  "detail": "The idempotency key was used with a different request."
}
Status Meaning
401 Missing or invalid token.
404 Missing route or action.
409 Idempotency conflict or invalid retry state.
413 Request exceeds 16 MiB.
422 Malformed JSON, invalid content type, fields, checks, workspace, or query values.
503 Unavailable worker or database.

Run the server provides an end-to-end request example.