Skip to main content
A session is one task run by an agent. Seventeen methods, one per route; objects parse with the core SessionSchema. API detail: Sessions, Events.

create

POST /v1/sessions. Creates and starts, with the initial message, in one call.
string
required
The agent to run.
string
required
The initial instruction.
number
Pin an exact version; default is the agent’s current one.
string
Completion window override: immediate, priority or loose. It sets the per-call price; a window the agent’s model does not serve is window_unavailable (400).
integer
Spend cap for this session, integer micro-USD.
string
The persona this task acts as — an idn_ id or the persona’s name. Answered as identity_id on the session.
object
JSON schema the final document must match.
boolean
Refuse a would-be clean ending that produced no document matching output_schema.
string
An outcome (ocm_…) to grade the session against from its first turn. An unknown one is not_found (404), and an agent that runs team members (any handoffs but false, or a multiagent roster) is validation_failed (400), before anything is quoted.
string
Set when a deployment fired this run.
object
Arbitrary key/value pairs.
string
plan starts the session in plan mode; build, the default, does not.
create, send and handoffs take an optional { idempotencyKey }, sent as the Idempotency-Key header and recorded as the client_message_id of the message the call writes. Without one the client mints a fresh key per call, so a retry you make yourself is a second create or send; pass the same key to make it a replay of the first.

list

GET /v1/sessions. SessionFilter adds agent_id, status, stop_reason, deployment_id, parent_session_id and handoff_from to the page query. handoff_from is a session id and lists the top-level sessions that session handed work to, newest first. stop_reason is how you find the sessions a person has to answer. A session held on an ask tool call is status: "idle" like every finished one — what separates it is stop_reason: "awaiting_approval", with the blocked call in pending_actions:
stop_reason: "awaiting_answer" is the same query for the sessions asking you a question rather than for permission — see answer. "budget_paused" is the same question asked about money, and "error" about failure.

get

GET /v1/sessions/{id}. The single read also carries outcome_evaluations[]: every outcome held over the session, oldest first, the last being the active one, each { object: "outcome_evaluation", session_id, outcome_id, result, iteration, explanation, attached_at }. result is pending until the first grade lands. A session with no outcome carries []; sessions.list does not join it.

needs

GET /v1/needs. Every question or approval waiting on a person, from any live agent of the company, oldest first. Each need carries its kind (question or approval), its agent ({ id, name }), since, and the parked session, whose pending_actions are the asks. Answer one with answer or confirmTool.

operatorPreview

GET /v1/sessions/{id}/operator_preview?tool_call_id=…. What an approval card shows for one parked operator.request, read from the account: { object: "operator_preview", tool_call_id, action, persona, title, verb, rows: { label, value }[], runnable, why }. why says what stops it when runnable is false. See Sessions.

send

POST /v1/sessions/{id}/messages. Sending to a running session is refused with session_running unless you say which of two things you mean: interrupt: true steers it mid-run; queue: true holds the message in the session’s inbox and it becomes the input of the turn that follows. On an idle session queue is a plain send. The two together are validation_failed. model runs the session on that model id from this message’s turn on. The result’s optional hint is set when the session was started for a board card that is now done or held by another session: the message went through, and the hint names the card and, when there is one, the session holding it.

handoffs

POST /v1/sessions/{id}/handoffs. Hands message from session {id} (the sender, a top-level session of yours) to each named agent, starting a top-level session per target marked metadata.handoff = { from_session, from_agent, key, depth }. Who may be named is the sender’s agent’s handoffs policy — the same admission the model’s send_to_agent goes through. A target that is refused is a row in refusals, not a thrown error; the batch resolves for the rest.
The work a session handed out is client.sessions.list({ handoff_from: root.id }); the work it delegated in-thread is threads.

threads

GET /v1/sessions/{id}/threads. The child sessions a coordinator delegated from {id} with send_to_agent wait: true — parent_session_id is {id}, and they ran on its budget. A handoff (wait: false, or handoffs above) is not here: it is a top-level session of its own, found by handoff_from.

interrupt

POST /v1/sessions/{id}/interrupt. Stops the current turn; an optional message tells the agent why. On a live session that is not running it changes nothing and returns the session as it was; on an ended one (completed, failed, cancelled) it is session_terminal (409).

confirmTool

POST /v1/sessions/{id}/tool_confirmations. Answers a session paused on a gated tool call. It carries a verdict and no payload, so it cannot answer a question — that is answer, below, and this route refuses a kind: "question" row rather than folding “allow” back at an agent that asked for a mailbox address. scope says how far the allow reaches. Omitted (or "call") it approves this one call. "session" grants the call’s tool for the rest of that session — every later call to the same tool name runs with no confirmation — and nothing else: one tool name, one session, gone when the session ends, never written onto the agent, and never valid on a deny. For a call through the tool invoker (tools_execute) the granted tool is the one named in its tool argument: the same target runs with no confirmation, any other target through the invoker is still confirmed.

answer

POST /v1/sessions/{id}/answers. Answers a session parked on a question it asked you. A session with stop_reason: "awaiting_answer" carries a kind: "question" row in pending_actions, holding the sentence the agent wrote and one to three fields. answers is keyed by those fields’ keys; a value is a string, or an array of them for a multiple choice:
Every key the question asked for must be present — except one the question marked optional, which is answered by leaving the key out entirely rather than by sending an empty string — and no other, so a wake can never find the thing the agent stopped for still missing. A choice answer is not limited to that field’s options: other defaults to true precisely so a person can say what the agent did not think of.

cancel

POST /v1/sessions/{id}/cancel. Terminal — the session cannot be resumed. Idempotent: an already cancelled session is returned as it is; a completed or failed one is session_terminal (409). There is no delete: cancel ends a session you are done with, and its record, cost and events are kept for the life of the organization.

setBudget

PATCH /v1/sessions/{id}/budget, body { cap_micro_usd }. Raise only — a cap at or below what is already consumed would be retroactive and is refused. Integer micro-USD.

setOutcome

POST /v1/sessions/{id}/outcome. Holds the session to an outcome; the next turn is graded. Answers the new evaluation at result: "pending", iteration: 0, and replaces the active outcome, whose unfinished evaluation ends interrupted.
  • The session must be idle: session_running (409) while it’s running, queued or waiting on a grade; session_terminal (409) once it has ended.
  • The agent must work alone (handoffs: false, no multiagent roster): validation_failed (400) otherwise. A team member’s thread is refused too.
  • Judged by the session’s own agent version. A session keeps the version it started on, so changing the agent’s handoffs afterwards does not change the answer for a session already running. To grade an agent you just switched to handoffs: false, start a new session.
sessions.get returns every evaluation as outcome_evaluations[]; the last is the active one.

plan

GET /v1/sessions/{id}/plan. The session’s living plan, version: 0 and empty until one is written. See Plan mode.

writePlan

PUT /v1/sessions/{id}/plan. The owner’s edit, a compare-and-set: a stale base_version throws ApiError with code: "version_conflict". It wakes nothing; the agent reads the edit next turn.

events

GET /v1/sessions/{id}/events — the same log client.stream serves, read as pages. after_seq is exclusive, so polling with the last seq you saw never re-reads it. includeAccepted: true also returns the opt-in types the list leaves out by default (message.accepted, handoff.sent, tool.confirm.resolved, tool.confirm.answered, session.mode, plan.updated and outcome.evaluation.*); see Events.