Documentation / API reference
Create a decision
Send caller-defined state and named questions through one model or a pinned policy.
POST
/v1/decide| state · required | String, object or array containing the input. Other root scalars are rejected. |
|---|---|
| questions · required | Nonempty map of up to 100 named questions. Every question needs a type and nonempty instructions. |
| policy / model | Select one, not both. Omit both to use the active policy. Example pinned policy: default-cascade@v1. |
| external_id | Optional correlation string (up to 200 characters). It is not a retry key. |
| idempotency_key | Optional retry key (1–200 characters), scoped to tenant and route. Prefer the Idempotency-Key header. |
Question types
| choice | criteria maps at least two stable option IDs to descriptions. The answer names the selected option. |
|---|---|
| score | criteria is an ordered list of at least two descriptions. The numeric answer is on the 0 to length−1 scale. |
| noul | Binary proposition. The answer’s noul value is a probability from 0 to 1, not a yes/no string. |
Request
JSON
{
"policy": "default-cascade@v1",
"state": {
"message": "The delivery window moved to Friday."
},
"questions": {
"topic": {
"type": "choice",
"instructions": "Classify the message.",
"criteria": {
"schedule": "Timing or dates",
"other": "Any other subject"
}
},
"mentions_date": {
"type": "noul",
"instructions": "Does the text mention a day or date?"
}
}
}Response
HTTP 200 · response excerpt
{
"status": "completed",
"branch": "answer_o",
"model": "decisions-staging-v1",
"answers": {
"topic": {
"type": "choice",
"choice": "schedule",
"confidence": 0.9,
"probabilities": {
"schedule": 0.94,
"other": 0.06
}
},
"mentions_date": {
"type": "noul",
"noul": 0.98
}
},
"usage": {
"input_tokens": 148,
"output_tokens": 24
}
}Confidence and probability fields depend on question type and available evidence. Do not assume every answer has a separate confidence field.