Skip to main content
POST
Append user/system events to a session

Authorizations

Authorization
string
header
required

A Recursion API key, created in the console under API keys.

Headers

Idempotency-Key
string

Replay-protection key in an organization-wide namespace shared by keyed mutations. It must contain 1 to 256 visible ASCII characters and be sent as exactly one header value. Request identity is the exact HTTP method, escaped path, raw query, and raw body bytes. The same request replays the original successful response; any different request returns 409 idempotency_conflict, and an active matching request returns 409 idempotency_in_progress. Completed receipts are retained for approximately 24 hours, pending claims may be reclaimed after approximately 1 hour, and no deduplication is guaranteed after expiry.

Required string length: 1 - 256
Pattern: ^[!-~]+$
x-tenant-id
string

Optional tenant consistency check. When present, it must name the tenant bound to the API key, including when x-organization-id is default.

Minimum string length: 1
x-organization-id
string

Organization in which to act. Required for a tenant-scoped API key. Optional for an organization-scoped key, where it must name that same organization. The value may be an organization id or default.

Minimum string length: 1

Path Parameters

sessionId
string<uuid>
required

Session id (UUID) as returned by managedAgentsStartSession or managedAgentsListSessions.

Body

application/json

Request body of POST /managed-agents/v1/sessions/{sessionId}/events. It has two mutually exclusive forms and events wins: send message for the common case of one plain-text user turn, or send events as ordered typed turns with provider-shaped content. An empty events array yields exactly one user turn built from message, which must not be empty or only whitespace. The handoff_resolved control form rejects all message and referenced-session fields. The response acknowledges durable acceptance of the turn, not the agent's reply.

actor
string

Who the turn is attributed to. Defaults to human:api when omitted.

events
object[] | null

Typed events to append instead of message. When present, message and the top-level actor are ignored.

interrupt
boolean
default:false

Interrupt the current operation before reading these messages. Delegated work continues; the session handles coordination. Omit or use false for ordinary Send. Requires update permission in addition to create.

message
string

Plain-text message to append as a single user turn. Used only when events is empty, and then required: a message that is empty or only whitespace is refused with 400.

referenced_session_ids
string[]

Prior sessions this session may read from this turn on, by session id, added to any it already has. Each id is authorized under your own scope and grants read access to the whole tree containing it; one you cannot read refuses the whole request with 404 and delivers no message. The grant is recorded before the message, so the turn it starts is the first one that can use it.

Maximum array length: 10

Response

Response body of POST /managed-agents/v1/sessions/{sessionId}/events. It acknowledges durable acceptance of the turn, never the agent's reply: read the reply by listing events or streaming. Compare events_accepted against what was sent to detect silently dropped entries, and read delivery_state to learn whether an agent is actually going to act on them. events_accepted counts canonical events rather than requests, so interrupt=true reports 2 for a single instruction: the interrupt and the message that follows it.

Response body of POST /managed-agents/v1/sessions/{sessionId}/events. It acknowledges durable acceptance of the turn, never the agent's reply: read the reply by listing events or streaming. Compare events_accepted against what was sent to detect silently dropped entries, and read delivery_state to learn whether an agent is actually going to act on them. events_accepted counts canonical events rather than requests, so interrupt=true reports 2 for a single instruction: the interrupt and the message that follows it.

delivery_state
enum<string>
required

How the accepted events reached a reader. queued: the agent was mid-turn, so the input is waiting outside the transcript and the next turn boundary will read it; interrupt to bring that forward. signaled: the running session was woken and will act on them. resumed: the session had already finished, so it resumed to act on them. stored: appended to the timeline with nothing running to act on them yet.

Available options:
stored,
signaled,
resumed,
queued
events_accepted
integer
required

How many canonical events were written or queued. This counts the inputs actually derived from the body, not its length: a plain message body yields 1, and a typed user.message with no content is dropped, so this can be lower than the events array sent.

Required range: -9007199254740991 <= x <= 9007199254740991
ok
boolean
required

Always true. Every event in the request was durably accepted; any partial or total failure is an HTTP error instead, so this field never reports false.