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

## Session schedules {#schedules}

These paths follow `/v1/namespaces/:namespace/agents/:agent/sessions/:session`:

| Method | Suffix | Purpose |
| --- | --- | --- |
| `GET` | `/schedules` | List schedules owned by this Session; filter by `name` or `state` |
| `GET` | `/schedules/:name` | Read the current definition, complete input, destination, and next due time |
| `GET` | `/schedules/:name/occurrences` | Inspect delivery, target Run, result reference, and scheduled time range |
| `DELETE` | `/schedules/:name` | Cancel future work and return accepted or unresolved deliveries |

URL-encode schedule names. Reads require `session:read`; cancellation requires `session:steer` on the owning Session. Collections accept `limit` from 1 to 200 and return `nextCursor`; pass that cursor on the same collection for the next page. A cancellation receipt's `deliveries.nextCursor` continues through the occurrence collection.

Register or replace schedules from Agent code with `ctx.schedule()`. Scheduled inputs use normal distinct-Run admission, and Run detail exposes `lineage.schedule`. See [Schedule Agent follow-ups](/docs/agents/schedules.md) for the SDK and lifecycle contract.

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