HTTP, gRPC and event streams

Route families

GET /build

Authenticated build identity JSON. Check the JSON content type and the returned version, commit and executable identity.

GET /whoami

Read resolved identity, namespace grants and the server’s grant vocabulary.

GET /health/live; GET /health/ready

Liveness and readiness are separate health readings.

POST /workflows/*

Start, signal, query, cancel, retire, rename, tag, reopen, list, describe, children, history and transcript operations.

/deploy/*

Deploy archives, list versions and workers, change routes and unload. Requires the enabled deploy surface and deploy authority.

/awl/*

AWL checking, source workspace, formatting, schemas and deployment. Document paths resolve under the configured workspace.

/schedules

Seven HTTP operations for creating, listing, describing, replacing, pausing, resuming and deleting schedules.

GET /events/stream

WebSocket event subscriptions. Per-workflow history and transcript streams have distinct sequence cursors.

/mcp

Public stateless HTTP MCP, enabled explicitly. Origin checks apply to browser clients.

/assistant

Assistant descriptor; session HTTP, WebSocket and private MCP routes are separate from public MCP.

GET /metrics

Prometheus metrics when enabled.

The generated protocol files and HTTP handlers define the precise request types. Public package sources are listed in releases and resources.

Payload forms

HTTP workflow start accepts an ordinary JSON value or the core payload envelope. The core content-type tag and the gRPC wire content type have different spellings. Use the form that the transport publishes; do not change a returned envelope’s tag by guessing.

{"namespace":"default","workflow_type":"greet_visitor","input":{"name":"Ada","enthusiastic":true}}

Schedule config uses the protocol envelope containing a UTF-8 byte array. The schedule guide uses a curl request with a pre-encoded UTF-8 payload.

Stream cursors

Per-workflow subscriptions use the first event sequence wanted. Sequence one reads the full retained history; the sequence after the head tails live changes. A zero or an ahead-of-history cursor is refused.

Transcript and cluster subscriptions use their own after-sequence cursor. Workflow event numbers, transcript store sequences and cluster sequences are not interchangeable.

Filtered and firehose subscriptions are live-only. They cannot represent one cross-workflow resume cursor. A disconnect or lag must be handled explicitly; read history where replay is available.

Authorization

HTTP, gRPC and public MCP resolve the same caller grants. A foreign namespace is answered without disclosing the execution. Deploy and assistant-session authority are separate from namespace access.

Read auth and Lys before opening a listener beyond a local evaluation.

Operational resources

The operational HTTP reference covers dead letters, unserved queues, recovery failures, changelog, update status and worker drain/stop.

Use namespace creation for closed automatic creation, activity control for interventions, and worker deployment routes for durable worker records.

Terms in response schemas