Agents, sessions, and Runs API
Invoke Agents, retrieve session and Run state, page events and journals, stream output, and delete a session safely.
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
| 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 /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.