# Agents, sessions, and Runs API

> Invoke Agents, retrieve session and Run state, page events and journals, stream output, and delete a session safely.

## Invoke {#invoke}

| Method | Path | Purpose |
| --- | --- | --- |
| `POST` | `/v1/events` | Dispatch a canonical event to an Agent CRN |
| `POST` | `/v1/namespaces/:namespace/agents/:agent/sessions/:session/events` | Invoke one Agent/session with `{ eventId, body, deliver }` |
| `POST` | `/v1/chat/completions` | Invoke through the built-in OpenAI-compatible Channel |
| `POST` | `/v1/messages` | Invoke through the built-in Anthropic-compatible Channel |

The canonical envelope contains `v: 1`, a caller-stable id, type, target Agent CRN, stable session id, data, and optional `deliver: "queue" | "live"`. The platform supplies the dispatcher source; callers cannot impersonate another Channel.

## Read workflow state {#read}

| Method | Session or Run suffix | Purpose |
| --- | --- | --- |
| `GET` | `/sessions/:session` | Bounded authoritative session state |
| `GET` | `/sessions/:session/events` | Page accepted events and ledger history |
| `GET` | `/sessions/:session/workflow` | Authoritative current workflow view |
| `GET` | `/sessions/:session/waits` | List open durable waits |
| `GET` | `/sessions/:session/runs/:run` | Read authoritative Run state |
| `GET` | `/runs/:run/detail` | Read bounded Run, facts, waits, steers, and newest journal page |
| `GET` | `/runs/:run/journal-window` | Page older or newer Console-oriented journal windows |
| `GET` | `/runs/:run/journal` | Read the cryptographically rooted journal interface |
| `GET` | `/sessions/:session/stream?runId=...` | Connect through SSE or WebSocket |

All session and Run suffixes follow `/v1/namespaces/:namespace/agents/:agent`. Detail accepts bounded journal limits and cursors; journal windows accept limits from 1 through 500.

## Delete a session {#delete}

`DELETE /v1/namespaces/:namespace/agents/:agent/sessions/:session` requires `session:delete` and a JSON `eventId` or `Idempotency-Key`. Deletion rejects new work, stops active execution, releases attachments, and preserves bounded progress. Read progress with `GET .../sessions/:session/deletion`. It is not a shortcut for deleting one Run.