Read a decision

After POST /v1/sessions/{session_id}/next, check action before deciding what to display. A warning does not automatically end the conversation.

Field	Meaning	Suggested action
`action: "ask"`	At least one candidate is available; `decision_id` is present and `stop_reason` is `null`.	Display a candidate and retain the decision for the next turn.
`action: "stop"`	No identifiable question remains; `candidates` is empty.	End or hand off the conversation.
`warnings`	Business signals about selection; not HTTP errors.	Adjust the conversation flow according to the signal.
`degraded: true` / `degraded_reasons`	Understanding this turn used a fallback. The `/next` response remains usable.	Log the reasons; do not present unconfirmed information as certain.
`stop_reason`	Reason for a hard stop; `null` when `action` is `ask`.	Do not confuse it with `warnings`.

Possible warnings

`warnings` value	Meaning
`max_turns_reached`	The soft turn limit was reached or exceeded; the API may still offer a question.
`objective_achieved`	The objective’s success conditions are met; your application decides whether to end.
`eligibility_exhausted_fallback`	The engine used a valid fallback question because the normally eligible pool was exhausted.
`constraints_relaxed`	A `prefer` selection preference was broadened; hard exclusions still apply.

Fallbacks and stops

degraded_reasons may include semantic_service_unavailable (semantic analysis unavailable), unresolved_previous_turn (previous question not resolved), or missing_user_text (a reply was absent when expected). summary_only_context remains in the schema, but a summary-only add_context is now a normal operation and is not flagged as degraded. The only current stop_reason is no_question_available: no question remains after hard exclusions. The turn limit and objective achievement produce warnings, not hard stops.

Example: action: "ask" with warnings: ["max_turns_reached"] means a question is available despite the limit. Your application decides whether to ask it or stop.

Get started

Guides

References

Resources

Read a decision

Possible warnings

Fallbacks and stops

​Possible warnings

​Fallbacks and stops

Possible warnings

Fallbacks and stops