Skip to content

The HTTP API is built on REST resource endpoints + SSE event streams. The openapi.yaml file is the authoritative interface definition.

  • Public API: /api/v1
  • Internal model runtime: /internal/v1/models/* (loopback only, no Authorization)
  • Host can inject a caller context resolver; without one, standalone server uses minimal caller context
  • Async entry points (send message, trigger action) return 202
  • Streaming uses SSE
  • Final execution status determined by the run resource
  • Sending a session message is non-interrupting by default; pass runningRunBehavior: "interrupt" if you want the new message to cancel the current active run first
  • The follow-up message queue is a server-side resource. Read it with GET /sessions/{id}/queue, and promote an already queued message with POST /runs/{id}/guide

Key boundaries: session = context boundary, run = execution boundary, runs within a session are serial.

File and command endpoints intentionally keep E2B-style sandbox semantics: routes live under /sandboxes, and sandbox roots are exposed as /workspace. This is a stable interface contract, not a temporary compatibility layer. The /workspaces API still remains for workspace metadata, catalog, and lifecycle concerns.

DocumentContent
openapi.yamlOpenAPI 3.1 specification
workspaces.mdWorkspace, catalog, model visibility
sessions.mdSessions and messages
runs.mdRun lookup, cancellation, and queued-run guide
actions.mdManual action triggering
files.mdSandbox file management and commands
storage.mdStorage inspection and maintenance endpoints
models.mdModel runtime
streaming.mdSSE event streaming
components.mdShared schemas and error models

The OpenAPI file is the interface source of truth. The Markdown pages explain intent, boundaries, and behavior.