Skip to main content
POST
Create a session

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

Body

application/json

Create a session pinned to the current published domain configuration.

client_reference
string

Optional client-side reference for correlating this session.

Required string length: 1 - 128
max_turns
integer

Turn limit for this session. Once it is reached, /next returns action=stop with stop_reason=max_turns_reached. It may be lowered to the account plan's cap; read the effective value from max_turns and turns_remaining in the response.

Required range: 1 <= x <= 100
initial_history
object[]

Optional conversation history supplied when starting a session after an earlier exchange.

Maximum array length: 100

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.