Does this need attention?
Supply criteria for true and false. Receive a numeric noul judgment, not a Boolean action.
Decisions API
A paragraph isn't a next step. A usable judgment is.
One state. Several named questions. One API call returns typed judgments—not a paragraph your application has to interpret.
Urgent?Likely
Destination?Billing
Frustration?Elevated
Illustrative judgments—not facts about the sender.
A dedicated endpoint, not a chat prompt
Ask for the shape your next step needs.
POST /api/v1/generations/decisions evaluates named questions against a shared state. Each answer keeps its question name and type.
Which of our teams fits?
Map your choice identifiers to descriptions. The answer returns the selected identifier in choice.
Where does this fit on our scale?
Supply an ordered list of criteria, with the first entry at the top of the scale. Reordering changes its meaning. Interpret the numeric score using the returned legend; do not assume its direction.
Inspect a request and illustrative response
Authenticate with a Bearer API key and a positive account balance. Replace YOUR_DECISION_MODEL with a supported decision-model identifier from the current API reference. The public general-purpose model catalog is not a guarantee of Decisions support. Each question needs non-empty instructions and criteria; question names and choice identifiers must also be non-empty.
Request body
{
"model": "YOUR_DECISION_MODEL",
"state": "My payouts have been failing for three days. I need this fixed today.",
"questions": {
"is_urgent": {
"type": "noul",
"instructions": "Does this message convey urgency?",
"criteria": {
"true": "Explicitly time-sensitive",
"false": "No urgency expressed"
}
},
"department": {
"type": "choice",
"instructions": "Which team should handle this?",
"criteria": {
"billing": "Money, payouts, invoices",
"support": "General help requests"
}
},
"frustration": {
"type": "score",
"instructions": "How frustrated is the customer?",
"criteria": ["Calm", "Frustrated", "Very angry"]
}
}
}Illustrative response shape
{
"id": "d_example",
"model": "CANONICAL_DECISION_MODEL",
"provider": "example-provider",
"answers": {
"is_urgent": {
"type": "noul",
"noul": 0.93
},
"department": {
"type": "choice",
"choice": "billing"
},
"frustration": {
"type": "score",
"score": 1.35,
"legend": {
"0": "Calm",
"1": "Frustrated",
"2": "Very angry"
}
}
},
"usage": {
"input_tokens": 120,
"output_tokens": 15,
"cost": 0.00042
}
}Illustrative values, identifiers and cost—not a live result or a price quote. The response is not wrapped in data. confidence and probabilities are provider-dependent and may be absent. The canonical response model name can differ from the requested alias.
For 400, correct invalid types, empty required fields or an unknown model before retrying. For 401, check the API key. For 402, check balance or quota rather than repeating the same call.
The judgment and the action are different
Your application owns the next step.
These sample judgments stay the same. Change the example application policy to see how the action can differ.
My payouts have been failing for three days. I need this fixed today.
Does this need urgent attention?
0.93Illustrative noul value—not a separate confidence field
Which supplied team fits?
BillingA choice from your department list
Where is the tone on your scale?
1.35 / 2Illustrative returned legend: 0 Calm · 1 Frustrated · 2 Very angry. Read scores against the returned legend, not an assumed direction.
Example application policy · not a model setting
Present the judgments to a person.
This example application requires a person to approve the destination. No routing action is executed here.
Suggest a priority Billing route.
This example rule uses the selected department and an urgency threshold. If its conditions are not met, the application requests review.
Worked example · fictional judgments and policies · no live call or action. Probabilities and confidence are model judgments, not guarantees of correctness.
Choose from known destinations
Return a department, topic or next step your application already understands.
Define what the scale means
Evaluate urgency or fit against your criteria, instead of parsing an improvised explanation.
Keep uncertainty in the workflow
Use explicit application rules to choose what can proceed and what needs review.
Decide here. Write the reply elsewhere.
Decisions evaluates questions; it does not generate the customer-facing reply or explain its reasoning. Use inference for the written response after your application chooses a path.
There is no chat history, tool execution or free-text reply in this endpoint. Evaluate your languages and consequential decisions on known examples before automating a branch.
Label matching or explicit criteria?
Classifier ranks labels by semantic similarity. Decisions answers named yes/no, choice and scale questions using the instructions and criteria you supply.
Start with a judgment you can check.
Define questions you can audit. Check that every requested name returns with the expected type. Missing confidence is not zero; do not apply a threshold to a field the provider did not supply.
Keep usage visible.
Decisions follows the selected model's token rates and your account's billing adjustments. A single call evaluates all supplied questions and reports their combined usage and charged cost. Group related questions against the same state rather than repeating that state across separate calls.
Decisions billing