Skip to main content
Decisions (Beta)

Decisions

Answer structured questions based on custom context (state) or recent Session context to determine whether a task is complete, select a business branch, or score against predefined levels.

The Decision API is currently in Beta. Interface definitions, response structures, and behavior may change in subsequent versions. Follow documentation updates and verify compatibility before using it in production.
A Decision can contain multiple questions, supporting choice questions (choice) and scoring questions (score). The create endpoint executes the judgment synchronously and saves the result. Records can then be retrieved by ID or listed with pagination.

Endpoints

MethodPathDescription
POST/api/v1/forward/decisionsCreate Decision
GET/api/v1/forward/decisions/{decision_id}Get Decision
GET/api/v1/forward/decisionsList Decisions

Choose an input mode

ModeUse caseBehavior
state (custom context)Use caller-provided text, structured data, and other content as the basis for judgment.Supply a non-empty JSON object; no Session is required.
session_idEvaluate a Session's execution progress or results.The server extracts the Session's recent available context.
Each request must provide exactly one of these modes. A Decision is an independent judgment operation; it does not send a new message to a Session or start a new Turn. Session input uses only relevant information from user.message, agent.message, session.error, and agent.artifact_delivered events. It does not read file contents, tool call processes, or subthread history. The judgment uses recent available context, which may not include the complete conversation history. Oversized input returns 422 decision_context_too_large. Reduce the context or questions before retrying. A Session with no available context returns 422 decision_context_unavailable.

Decision object

Successful creation responses, detail queries, and listed records share the following structure.
FieldTypeDescription
idstringDecision ID, prefixed with dec_.
session_idstring or nullThe associated Session ID for Session input; null for explicit state input.
sourcestringCurrently fixed to api.
statusstringrunning, completed, or failed.
questionsarrayThe questions for this judgment. For the structure, see Create Decision.
answersarrayAnswers in the order of the request questions; [] when unfinished or failed.
contextobjectInput mode and context scope. See the table below.
errorobject or nullContains code and message on failure; otherwise null.
created_atstringCreation time in RFC 3339 format.
completed_atstring or nullExecution end time in RFC 3339 format; null while running, and a timestamp after success or failure.
Query results do not return the original state or a complete Session input snapshot.

Answer structure

typeResult fieldDescription
choicevalueReturns the selected option's original string or boolean value, preserving its JSON type.
scorescoreReturns the numeric score defined for the selected level, not a freely generated continuous score.
When a question includes name, its answer returns the same field. When omitted, questions and answers correspond by array position.

Context fields

The following fields are returned according to the input mode and execution progress. During execution or when input preparation fails, only mode may be present. Clients should tolerate missing optional fields and fields added in later versions.
FieldTypeDescription
modestringstate or session.
anchor_event_idstringThe latest candidate event ID determined during this read.
first_event_idstringThe earliest valid event ID actually included in the judgment.
last_event_idstringThe latest valid event ID actually included in the judgment.
included_segment_countintegerNumber of included context segments. Returned only in Session mode.
included_event_countintegerNumber of included valid events. Returned only in Session mode.

Workflow

  1. Prepare state or an accessible session_id, and define the questions and candidate answers.
  2. Call the create endpoint. A fixed Idempotency-Key is recommended for each logical operation. See Idempotent retries.
  3. Process choice or scoring results according to answers[].type.
  4. Save the Decision ID and track results with the detail or list endpoint. If creation returns an error containing error.decision_id, use that ID to query the failed record as well.