API surface
A stable contract for every client surface.
WebUI, TUI, Desktop, and external integrations should all talk to the same runtime API. Start with the reference, then drill into resources and schemas as needed.
/workspaces /sessions /runs /runs/{id}/events Use predictable endpoints for workspaces, sessions, runs, actions, files, models, and storage.
Subscribe to execution progress and state changes without making clients own the engine loop.
Validate workspace settings, actions, hooks, model providers, prompts, and server configuration.
Create, inspect, and operate durable workspace records.
Resource SessionsGroup user-visible interaction state around workspaces.
Resource RunsSubmit and track agent execution loops.
Resource ActionsExpose tool-like actions through the runtime contract.
Resource FilesCoordinate file access and workspace artifacts.
Resource StreamingConsume progress and state changes over SSE.
Contract maintenance
Keep API changes connected to runtime behavior.
The API pages should be the public face of the engine, not a disconnected reference list.
Use the design notes when adding or changing resource boundaries, naming, or streaming behavior.
Schemas Validate configuration shapeUse schemas when API payloads touch workspace settings, runtime config, hooks, actions, or providers.
Engine Trace runtime consequencesUse engine docs when endpoint behavior changes queue state, run lifecycle, projection, or event output.