Runtime API

Koda exposes runtime operations through /api/runtime/* and runtime WebSockets. These routes power the dashboard's task rooms: queues, environments, schedules, task detail, RunGraph, replay, artifacts, workspace views, terminals, browser state, and control actions. They do not currently ship as a separate OpenAPI document.

Authentication

• Operator session. The dashboard uses the koda_operator_session cookie. Same-origin runtime calls inherit it automatically.
• Runtime token. RUNTIME_LOCAL_UI_TOKEN guards dashboard-to-runtime traffic when the runtime is contacted directly.
• Control-plane token. CONTROL_PLANE_API_TOKEN is for trusted CLI or automation access through the control-plane boundary.

Health

The runtime readiness route is GET /api/runtime/readiness. It is the canonical readiness probe used by the dashboard and control plane.

$curl https://koda.example.com/api/runtime/readiness | jq

Queues and environments

• GET /api/runtime/queues — queue depth and runtime queue status.
• GET /api/runtime/environments — runtime environments.
• GET /api/runtime/environments/:env_id — environment detail.
• GET /api/runtime/schedules, POST /api/runtime/schedules, GET /api/runtime/schedules/:job_id, PATCH /api/runtime/schedules/:job_id, and POST /api/runtime/schedules/:job_id/actions/:action — schedule inspection and control.

Tasks

• GET /api/runtime/tasks/:task_id — task detail bundle.
• GET /api/runtime/tasks/:task_id/run-graph — RunGraph evidence for the task.
• GET /api/runtime/tasks/:task_id/replay — replay bundle when enough trace data exists.
• GET /api/runtime/tasks/:task_id/sandbox-doctor — task sandbox diagnostics.
• GET /api/runtime/tasks/:task_id/events, /artifacts, /checkpoints, /terminals, /browser, /browser/screenshot, /services, /resources, /loop, and /sessions expose the runtime panes shown in the dashboard.
• GET /api/runtime/artifacts/:artifact_id/download streams object-backed artifacts.

Workspace resources

Task workspaces are exposed through separate routes so the dashboard can load tree, file, search, status, and diff panes independently.

• GET /api/runtime/tasks/:task_id/workspace/tree
• GET /api/runtime/tasks/:task_id/workspace/file
• GET /api/runtime/tasks/:task_id/workspace/search
• GET /api/runtime/tasks/:task_id/workspace/status
• GET /api/runtime/tasks/:task_id/workspace/diff

Response shape

Runtime responses are dashboard bundles, not SDK models. Exact field shapes live in the runtime implementation and dashboard contracts. Expect task identifiers, status, timestamps, related-resource URLs, and endpoint-specific evidence payloads.

{
  "id": 42,
  "status": "running",
  "created_at": "2026-05-20T11:05:21Z",
  "updated_at": "2026-05-20T11:05:22Z",
  "resources_url": "/api/runtime/tasks/42/resources",
  "run_graph_url": "/api/runtime/tasks/42/run-graph"
}

Control actions

• Task actions: cancel, interrupt, retry, recover, pause, resume, save, attach/terminal, attach/browser, pin, unpin, cleanup, and cleanup/force.
• Session actions: POST /api/runtime/sessions/messages, /sessions/:session_id/cancel, /pause, and /resume.
• Workspace writes: workspace/write, workspace/create, workspace/delete, and workspace/rename.
• Process control: POST /api/runtime/processes/:process_id/terminate.

Status codes

• 200 — success.
• 202 — accepted asynchronous work.
• 400 — malformed request or invalid action.
• 401 — missing or invalid session/token.
• 403 — authenticated but not allowed or policy denied.
• 404 — no such task, session, artifact, process, or resource.
• 409 — lifecycle conflict.
• 429 — rate limited. Retry with backoff.
• 503 — runtime dependency is not ready.

Rate limits

Runtime routes go through the authenticated dashboard/control-plane boundary. Execution still enforces per-agent policy, queue limits, sandbox rules, channel identity decisions, and lifecycle controls inside the runtime service.

Next steps

• Control-plane API — configuration, proposals, evals, channels, MCP, and access.
• Runtime concepts — the lifecycle and internal services that back these endpoints.