Skip to main content
POST
Apply session events

Authorizations

Authorization
string
header
required

Send the domain-scoped API key as Authorization: Bearer . Never send client-supplied identity headers.

Headers

Idempotency-Key
string
required

Unique key per logical mutation; reuse the same key and body when retrying after a timeout.

Required string length: 8 - 128

Path Parameters

session_id
string
required

Server-issued session ID in the path.

Required string length: 1 - 128

Body

application/json
state_version
integer
required
Required range: x >= 0
context_update
object
required

Context added since the preceding call, as either a compact summary or an ordered message delta.

client_updates
object

Confirmed data or progress explicitly supplied by the integrating application.

Response

Successful response.

request_id
string
required
session_id
string
required
client_reference
string | null
required
status
enum<string>
required

stopped: the conversation ended. /next returned action=stop, or /events reached max_turns or left no question available. A session stopped by max_turns_reached offers no further question.

Available options:
active,
completed,
stopped
turn_count
integer
required
Required range: x >= 0
max_turns
integer
required
Required range: x >= 1
turns_remaining
integer
required
Required range: x >= 0
question_state
object
required

Question outcomes are stored as records rather than separate asked, answered, and refused ID lists.

targets
object
required

Sparse state: absent targets are unknown and uncovered.

progress
object
required
pending_decision
object | null
required

Decision still awaiting an observed answer or outcome. /events replaces it with a new decision when the updated state makes other questions more useful.

degraded
boolean
required
versions
object
required

Public engine and API versions plus the session state version. The session's pinned configuration version is not exposed or client-selectable.