A structured output API that answers inside your schema
Ask a generative model for JSON and you still have to check it. This API inverts the job: you declare the answers that exist, and the model returns a distribution over them.
What “structured output” still costs you
Schema-constrained generation has made valid JSON easier to obtain, but validity is only the first property of a useful answer. The harder questions are whether the label is one you declared, whether the answer is inside the enumerated options, and how sure the model was.
A decision model answers those by construction, because the output space is the question you asked. You send typed questions — a choice over a closed label set, a yes/no as one probability, a score over ordered levels — and receive a probability for every allowed answer.
- The returned label is always one you declared in the request.
- Every option comes back with a probability, including the ones that lose.
- The shape cannot drift between calls, because it is the request rather than a prompt.
Structured output, JSON mode, tool calling
None of these is strictly better; they answer different questions. JSON mode is the right tool when the answer is a document — a summary, a draft, a record with free-text fields. The decision API is the right tool when the answer is a choice among bounded options.
| Approach | What you get | What you still own |
|---|---|---|
| JSON mode | Well-formed JSON when the model complies | Validation, retries, and agreement on what each field means |
| Tool / function calling | A function name and its arguments | The tool, the schema, and the case where the model calls nothing |
| Decision API | A distribution over the answers you declared | A threshold, and the action behind each answer |
The guarantees a caller can test
Every answer names the model and the provider that produced it, the latency it took and a requestId. Each question’s answer carries the type it was asked as, so a consumer can type-switch without guessing.
- Every declared option appears in probabilities, and the distribution sums to one.
- A choice answer names a label from the request, never a new one.
- A score answer stays within its declared levels and returns a number, not a bucket somebody picked in advance.
- A refusal is a status, a stable code and a requestId — never an empty 200.
Failures are part of the contract
When the provider cannot answer, this API returns 502 model_unavailable and charges nothing. The deterministic lexical scorer only runs if you ask for it with allowDegraded: true, and then the answer says degraded: true and names the fallback as its provider. A caller who was promised a model decision never silently receives a different kind of decision.
When this is the wrong tool
If the answer is a paragraph, a code edit or an open-ended extraction, a decision model is the wrong shape — use a model that writes. This API is for bounded choices: routing, labelling, scoring, moderating and gating. The schema is the point; when there is no closed set to enumerate, there is no advantage here.
Frequently asked questions
Is this the same as JSON mode?
No. JSON mode constrains syntax; this API constrains the answer set. You get a probability for every option you declared, and the winning answer is one of them by construction.
Can I get free text back?
Not from this endpoint, by design. If the output is prose, use a generative model — the decision model vs LLM page covers where the line sits.
Which question types are supported?
Choice over a closed label set, noul (a yes/no as one probability) and score over ordered levels. The keyed endpoint takes typed questions with instructions and criteria; the free endpoint takes prompt and options.
What happens if the model cannot map its answer to the schema?
The call fails as 502 model_unavailable and nothing is charged. The API does not repair the answer, guess a label or return a half-valid body.
Keep reading
Model notes
One short email when a new decision model lands or a benchmark changes. No spam, unsubscribe in one click.