Send events — the one input: user.message, user.interrupt, system.message [write]
Changed onThe conversation plane (edge-routed to the chat-proxy). Body {events: [...]} (1–50), optionally requireIdle: true for one user.message (and optional trailing system.message). Exclusive admission refuses a busy session with 409 before persisting or delivering the message; a successful echo's user id names the admitted run. Its admission field is created only when this POST committed the exclusive input; an idempotent replay returns replayed. This field is not part of history or SSE. This is a Session admission receipt, not proof that another client's earlier queued joined input has finished on the Pod. Ordinary sends may join an open run. validated all-or-nothing. A user.message carries content blocks: text, image and document with base64 / url / file sources (inline base64 ≤ 20 MiB per request; larger content goes through POST /files). A user.message may set interaction_mode: "plan" (the agent inspects and answers with a reviewable plan, then waits for a choice to implement) or "build"; omitted, the session's own metadata.interaction_mode applies (build when unset). A system.message (text only) must be last and follow the user.message it accompanies: privileged context for that turn and, through the agent's transcript, later turns. user.interrupt stops the in-flight turn; with mode: "save" it instead asks the run to start no new work, save what it has (files plus a progress note in the working directory) and end its turn with a reply listing what was saved, and stops it only if it is still running after a 10 minute grace window (echo status saving, or no_turn when nothing is running). A later user.message continues in the same session. Every event echoes back in the history shape with a stable id; sources are echoed as file sources naming per-session copies (never base64). Optional Idempotency-Key header: a replay returns the original echo. 402 insufficient_credits / budget_reached, 503 egress_policy_failed, 400 session_archived refuse the whole request before any row is written.
Request
- Base URLhttps://api.agentsky.dev/v1
- URLhttps://api.agentsky.dev/v1/sessions/{id}/events
- AuthHTTP bearer
Path parameters
The session id
Request body
Response
OK — one echo per event, in order
Changes
- breaking
removed
subschema #1subschema #3from the/request propertyoneOflist - info
added
subschema #1subschema #3to the/request propertyoneOflist - info
added the optional property
//////to the response with the status - info
added the optional property
//////to the response with the status - info
added the optional property
//////to the response with the status - info
added the optional property
//////to the response with the status - info
added the optional property
/to the response with the status - info
the response property
became required for the status - info
the response property
/became required for the status - info
the response property
/became required for the status
- breaking