structured output api

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.

ApproachWhat you getWhat you still own
JSON modeWell-formed JSON when the model compliesValidation, retries, and agreement on what each field means
Tool / function callingA function name and its argumentsThe tool, the schema, and the case where the model calls nothing
Decision APIA distribution over the answers you declaredA threshold, and the action behind each answer
Both contracts are served here: typed questions with instructions and criteria on the keyed endpoint, prompt and options on the free one.

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.