# HTTP, gRPC and event streams

Find the server transport families, payload forms, cursors and route gates.

Aion serves HTTP/JSON, gRPC and WebSocket event streams. Most CLI client operations use gRPC. Tail and signal dry-run also read HTTP endpoints. The console uses the HTTP and stream surfaces; public MCP uses the same HTTP listener.

## 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](/aion/reference/sources/).

## 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.

**HTTP workflow start body**

```json
{"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](/aion/operations/schedules/) 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](/aion/operations/auth-and-lys/) before opening a listener beyond a local evaluation.

## Operational resources

The [operational HTTP reference](/aion/reference/http-operations/) covers dead letters, unserved queues, recovery failures, changelog, update status and worker drain/stop.

Use [namespace creation](/aion/operations/namespaces/) for closed automatic creation, [activity control](/aion/operations/activity-control/) for interventions, and [worker deployment routes](/aion/reference/http-worker-deployments/) for durable worker records.

## Terms in response schemas

- `incarnation`: One particular launch of a server process, identified by its process record and executable identity.
- `lowering`: Converting checked AWL into executable code during compilation.
- `provenance`: The source of a value or reading, such as recorded history, a live process or a selected configuration file.
- `projection`: A read view computed from recorded events or stored records.
- `residency`: Whether a workflow execution is currently loaded as a live process in the engine.