The endpoint is fast; the contract makes it dependable
OpenAI made the Decisions API generally available on October 22, 2026. The dedicated POST /v1/decisions endpoint uses GPT-6 Luna to answer bounded questions over text, images, JSON, or conversation history. OpenAI positions it for classification, routing, prioritization, and other repeated judgments, with latency up to ten times lower than using Luna through the Responses API.
That shape is genuinely useful. An application that only needs “duplicate charge: yes or no,” “route to billing, returns, or fraud,” or “severity from cosmetic to blocked” should not pay the latency and parsing cost of a paragraph. Typed answers reduce output ambiguity and make downstream code easier to test.
But typed does not mean deterministic. The answer still depends on the model, question wording, allowed choices, score-level definitions, shared evidence, ordering, context length, model revision, and production distribution. The response can refuse. A confidence value is not a guarantee. A probability that a call is risky is not proof that the caller is authorized.
The production unit is not “GPT-6 Luna returned 0.91.” It is question version + evidence version + answer distribution + threshold version + fallback + policy decision.
OpenAI's official Agents SDK examples make the same boundary explicit: use labeled application data to choose thresholds, stop on API failure or refusal, and keep actual permission enforcement in trusted application code. That is the right mental model. Decisions narrows uncertainty for a bounded question. Your system still owns correctness, authority, and recovery.
Three answer types encode three different claims
A request contains a model, shared input, and one or more named questions. Today the supported model is gpt-6-luna. Shared input may be text or an ordered conversation containing messages, tool calls, and matching tool outputs. User content can also carry structured JSON. Each question defines its own instructions and, where needed, choices, score levels, or images.
| Type | What it asks | Returned evidence | Common misuse |
| Predicate | Is a condition true? | Probability from 0 to 1 | Treating probability as a verified fact |
| Choice | Which allowed category fits? | Selected value, confidence, full probabilities | Using overlapping or incomplete choices |
| Score | Where does evidence sit on ordered levels? | Weighted score, confidence, per-level probabilities | Writing adjacent levels with indistinguishable criteria |
| Refusal | The model declines one question | Named refusal while other answers may still succeed | Coercing a default into an ordinary answer |
A score is especially easy to misunderstand. It is a probability-weighted average of level indices, so it can fall between named levels. If the levels are cosmetic, workaround available, and fully blocked, a result of 1.1 is not a new severity class. It summarizes a distribution. Keep the distribution when making a consequential decision; the scalar alone hides disagreement.
Questions in the same request share evidence but are not a workflow language. If question B should only run after question A passes, send a second request. Packing dependent questions into one batch lets the second answer see evidence, not the first model answer or your intervening policy result.
{
"model": "gpt-6-luna",
"input": [{
"role": "user",
"content": [
{"type": "input_text", "text": "Evaluate this support case."},
{"type": "input_json", "data": {
"ticket": {"text": "I was charged twice."},
"order": {"charge_count": 2, "amounts": [49, 49]}
}}
]
}],
"questions": [
{
"type": "predicate",
"name": "duplicate_charge_supported",
"instructions": "Is a duplicate charge supported by the order record?"
},
{
"type": "choice",
"name": "review_queue",
"instructions": "Which specialist queue should inspect this case?",
"choices": ["billing", "fraud", "order_support"]
}
]
}
Use the narrowest primitive that actually expresses the task
Decision models occupy a useful middle layer between deterministic rules and generative work. They are a poor replacement for either. If a rule can be expressed exactly from trusted fields, write code. If the application needs an explanation or a generated object, use the Responses API with Structured Outputs. If the model should propose a tool call and arguments, use function calling, then authorize the call separately.
| Primitive | Best fit | Output shape | Authority |
| Deterministic code | Known rules, limits, schema validation, permission checks | Exact programmed result | May enforce policy when code is trusted and reviewed |
| Decisions API | Ambiguous but bounded classification, ranking, predicates, triage | Predicate, choice, score, or refusal | Evidence for policy, never permission by itself |
| Structured Outputs | Extraction, explanation, or generated objects with a custom schema | Schema-conforming generated object | Proposal requiring validation and policy |
| Function calling | Model proposes which tool to call and with what arguments | Tool name and arguments | Application authenticates, authorizes, validates, and executes |
A good Decisions task has a finite answer space, repeatable evidence, an observable target label, and a reversible downstream action. A bad task asks the endpoint to invent policy, infer an employee's legal status, approve a payment, or decide whether a user deserves access without an independent identity and authorization system.
The choice set is part of the product design. “Sales,” “support,” and “other” may look exhaustive while hiding fraud, privacy, legal, and security cases inside “other.” Create an explicit abstain or specialist-review route where the cost of forced classification is high. A model that must always pick one of three inadequate labels will do exactly that.
Put the model between evidence assembly and policy evaluation
1. AssembleValidate identity, source records, schema, freshness, and allowed evidence fields.
2. DecideSend a versioned question set and evidence contract to the Decisions API.
3. InterpretHandle answer, distribution, confidence, refusal, timeout, and API error without coercion.
4. Evaluate policyApply calibrated thresholds, deterministic exclusions, user permissions, limits, and approval rules.
5. Act or queueExecute only authorized reversible actions; otherwise route to a human or deterministic fallback.
6. LearnJoin the receipt to later ground truth, overrides, incidents, and slice metrics.
Keep the evidence assembler boring. It should reject missing required fields, normalize units, preserve source IDs, and separate untrusted customer text from system instructions. JSON support removes the need to stringify records, but it does not validate whether the record is authoritative or current.
Give every question a stable name and a versioned specification. The specification should record instructions, answer type, allowed choices or levels, input fields, excluded fields, labeled dataset, cost matrix, thresholds, fallback, owner, and expiry. Changing “Does this look risky?” to “Is there evidence of fraud?” is not a copy edit; it changes the target.
decision_contract:
id: support-duplicate-charge/v3
model: gpt-6-luna
evidence_schema: support-case/v5
question_set_hash: sha256:...
thresholds:
auto_route_min_confidence: 0.88
human_review_below: 0.88
deterministic_blocks:
- missing_order_id
- currency_mismatch
- customer_identity_unverified
refusal: human_review
api_error: queue_without_action
authority: routing_only
calibration_set: dup-charge-2026q4@sha256:...
Calibrate against business cost, not a pleasing confidence number
Start with labels defined independently of the model. For a support router, a resolved-case owner or reviewed policy outcome may be the label. For visible damage, use adjudicated image labels with disagreement tracked. Split train-like examples used to design the question from a locked acceptance set used to judge it.
Measure by slice. A single accuracy number can hide failure on a language, product, image quality, account type, region, or new policy version. At minimum, report coverage, precision, recall, false-positive and false-negative rates, refusals, human-review rate, latency percentiles, and cost per accepted decision. For scores, inspect calibration curves and confusion between adjacent levels.
Threshold selection is an operations decision. If a false negative can release fraud while a false positive only adds a review task, the two errors do not have equal cost. Include reviewer capacity: a threshold that sends 60 percent of traffic to a queue may be statistically cautious and operationally unusable.
def route_case(decision, policy, actor):
if decision.api_error or decision.refusal:
return queue("human-review", reason="no-valid-model-answer")
assert actor.is_authenticated
assert policy.allows(actor, "route_support_case")
answer = decision.answers["review_queue"]
if answer.confidence < policy.route_threshold:
return queue("human-review", reason="below-threshold")
if answer.choice not in policy.allowed_queues:
return queue("human-review", reason="unknown-choice")
receipt = record_decision(
question_version=policy.question_version,
evidence_digest=decision.evidence_digest,
distribution=answer.probabilities,
threshold_version=policy.threshold_version
)
return route(answer.choice, receipt=receipt)
Shadow production traffic before enforcement. Compare model answers with the current route without changing state, then review disagreements. Canary one reversible lane with a kill switch. Recalibrate after question edits, model changes, new data fields, policy changes, distribution shifts, or incidents. A threshold is a versioned control, not a universal constant.
Worked example: route a duplicate-charge complaint without auto-refunding
A customer writes, “I was charged twice.” The application retrieves the authenticated account, order, payment attempts, settlement states, currency, refunds, and prior disputes. Deterministic checks first confirm that the order belongs to the authenticated account and that record timestamps and currency agree.
The Decisions API answers two bounded questions: whether the records support a duplicate-charge condition and which review queue fits. The application keeps the predicate probability and the entire choice distribution. If evidence is missing, the model refuses, confidence falls below the calibrated threshold, or the deterministic identity check fails, the case enters human review without issuing money movement.
Even a strong duplicate-charge result does not authorize a refund. The payments system must verify settlement, refund eligibility, amount, original rail, prior refund status, fraud flags, limits, and the human or policy authority for release. The decision result improves triage. It does not replace the refund control.
Later ground truth closes the loop. Record whether the reviewer confirmed a duplicate, changed the route, found a third failure class, or discovered bad source data. Join that outcome to the exact question, evidence schema, model, distribution, threshold, policy, and action receipt. Otherwise the team can count decisions but cannot learn whether they were right.
A classifier is not an authorization mechanism
The most dangerous integration is an apparently elegant risk gate: ask whether a tool call is safe, then execute above or below a threshold. The model may be useful for risk evidence, but it does not authenticate the user, prove consent, establish the tool's current schema, check tenant boundaries, enforce spend limits, or know whether a manager revoked access one second ago.
OpenAI's official Agents SDK recipes deliberately leave thresholds, evidence, and permission enforcement with the application. They also document important edges: converted or defaulted tool arguments may require manual approval, realtime context differs, resumed runs have different callback behavior, and direct Decisions usage remains separate from an agent runner.
Build the hard boundary in code. Resolve the principal and agent identity. Validate the exact tool and normalized arguments. Apply resource, tenant, amount, time, rate, data, and destination constraints. Require step-up approval where policy says so. Bind approval to an immutable action digest. Only then can a model score influence whether the system blocks, queues, or requests approval.
This separation also improves incident response. When a model misclassifies a call, the team can identify a calibration defect without wondering whether the same model invented and enforced its own authority. Policy logs explain why an action was allowed. Decision receipts explain which uncertainty signal informed that policy.
Batching and caching change economics and failure shape
The GA endpoint supports up to 400 questions per request. That can amortize shared evidence, but only when the questions are truly parallel. A large batch can create correlated failure: one stale record, ambiguous shared instruction, or evidence omission affects every answer. Keep unrelated risk domains separate so one malformed support case cannot contaminate security, fraud, and compliance judgments in the same request.
Prompt caching can reduce repeated-input cost. Treat the cache identity as part of the contract. Shared instructions and reference evidence need an explicit version and freshness rule. A cache hit is not proof that the content is still applicable. When a policy changes, rotate the cache namespace or input so old context cannot survive the control change.
Measure cold and warm latency separately. Community reports after launch discussed noticeable cold-start differences, while official material reports large gains against a full Luna response. Both can be true. Capacity, region, payload size, cache state, concurrency, and question count determine the latency users actually see. Benchmark your route, not the headline.
Record regional processing and data-control decisions alongside each production use. Zero Data Retention and regional processing have eligibility and configuration requirements. Do not infer that the endpoint's technical availability automatically satisfies an organization's privacy, records, contractual, or regulatory obligations.
Failure modes to inject before release
| Failure | Why it looks safe | Required response |
| Overlapping choices | One value still wins | Rewrite taxonomy and test disagreement |
| Missing evidence | Model fills the pattern | Schema validation and refusal/human queue |
| Threshold copied from a demo | Confidence appears precise | Calibrate on labeled production slices and costs |
| Dependent questions batched | All answers return together | Stage requests after deterministic policy decisions |
| Refusal coerced to default | Pipeline stays green | Preserve refusal and stop or review |
| Cache survives policy change | Latency improves | Version cache inputs and expire stale context |
| Distribution shift | Aggregate accuracy remains stable | Slice monitoring, drift alert, shadow recalibration |
| Score becomes permission | Automation is fast | Authenticate and authorize in trusted code |
| API timeout or regional fault | Retry eventually succeeds | Idempotent queue, bounded retry, no unsafe default |
| Question changes without version | Endpoint and name stay the same | New contract version, acceptance set, and threshold review |
A four-stage production rollout
- Frame one decision. Choose a high-volume, bounded, reversible task. Name the target label, evidence, answer type, owner, prohibited uses, fallback, and measurable business cost.
- Build the acceptance set. Freeze representative labels, edge cases, missing evidence, adversarial wording, language and product slices, refusal expectations, and deterministic exclusions.
- Shadow and calibrate. Run current traffic without changing state. Measure distributions, errors, refusals, latency, cost, queue load, and reviewer overrides. Choose thresholds from the cost matrix.
- Canary one lane. Enable only a reversible route with bounded volume, a kill switch, fail-closed error handling, immutable receipts, and named on-call ownership.
- Expand by evidence. Require stable slice metrics, acceptable reviewer capacity, tested rollback, cache-version controls, authorization separation, and incident drills before each increase.
- Reopen on change. Model, question, evidence schema, choices, score levels, threshold, cache, region, policy, traffic, and downstream action changes all trigger review.
The acceptance criterion is not “the request returned a typed answer.” It is that the system can prove what it asked, what evidence it supplied, how the answer was distributed, which threshold and policy applied, what action followed, and whether later ground truth supported the decision.
Frequently asked questions
What is the OpenAI Decisions API?
It is a dedicated GPT-6 Luna endpoint for bounded judgments over text, images, JSON, and conversation/tool evidence. It returns predicates, choices, scores, or refusals rather than a free-form response.
Can it replace a rules engine?
No. Keep exact rules, schema validation, identity checks, permissions, limits, and legal or contractual requirements in deterministic policy. Use the model where evidence is ambiguous but the answer space is bounded.
Is confidence calibrated probability?
Do not assume universal calibration. Test the returned values against labeled examples from your own application, by slice, and choose thresholds based on error cost and review capacity.
Should low confidence mean denial?
Sometimes, but make the fallback explicit. Low confidence, refusal, missing evidence, and API failure may require human review, deterministic routing, or a safe denial depending on the task. Never silently convert them to approval.
When should developers use Structured Outputs?
Use Structured Outputs when the application needs a generated object with a custom schema or explanation. Use Decisions for a predicate, one fixed choice, or an ordered score.
Can Decisions approve an agent tool call?
The score can inform a risk gate, but trusted application code must authenticate the principal, normalize arguments, enforce policy and limits, bind approvals, and execute. The classifier is not authorization.
Sources and further reading
Sources were accessed November 8, 2026. Product capability and pricing claims are attributed to current OpenAI material. Repository examples describe implementation boundaries. Community posts are bounded practitioner signals, not benchmark consensus.
- OpenAI: Build more responsive apps with the Decisions API - October 22 GA announcement, product positioning, additions since beta, pricing, regions, and evaluation guidance.
- OpenAI Developers: Decisions guide - current request mechanics, answer types, JSON/images/conversation inputs, batching, evaluation, and primitive-selection guidance.
- OpenAI API reference: Create a decision - exact answer unions, refusal behavior, probability fields, and usage shape.
- OpenAI API changelog - October beta and GA chronology plus adjacent caching and service changes.
- OpenAI Agents SDK: Decisions recipes - classification, routing, tool-risk examples, fail-closed behavior, limitations, and authorization boundary.
- OpenAI Agents SDK issue 5353 - design discussion and resolution preserving native-client composition and application-owned permission policy.
- OpenAI Cookbook: customer request routing - runnable bounded-choice example and API use pattern.
- OpenAI Developer Community: GA discussion - current implementation discussion and cache-oriented observations.
- r/OpenAI: launch availability discussion - practitioner questions before public beta; historical context, not current availability.
- r/LLMDevs: Jev, Clef, and Decisions comparison - anecdotal cold-start and implementation signal.
- Related: calibrate a typed decision router.
- Related: keep agent permission outside the model.
- Related: turn action traces into execution receipts.