Decision models | November 8, 2026

OpenAI Decisions API needs a calibration contract, not an authorization shortcut

Predicates, choices, and scores can make high-volume routing much cheaper and faster than a full generated response. They are still model judgments. Version the question, evidence, threshold, fallback, and authority boundary before a probability can change production state.

GPT-6 Luna Calibration Fail-closed fallback Evidence checked Nov 8
Typed model decisions passing through calibration, policy, and human review before application execution

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.

TypeWhat it asksReturned evidenceCommon misuse
PredicateIs a condition true?Probability from 0 to 1Treating probability as a verified fact
ChoiceWhich allowed category fits?Selected value, confidence, full probabilitiesUsing overlapping or incomplete choices
ScoreWhere does evidence sit on ordered levels?Weighted score, confidence, per-level probabilitiesWriting adjacent levels with indistinguishable criteria
RefusalThe model declines one questionNamed refusal while other answers may still succeedCoercing 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.

PrimitiveBest fitOutput shapeAuthority
Deterministic codeKnown rules, limits, schema validation, permission checksExact programmed resultMay enforce policy when code is trusted and reviewed
Decisions APIAmbiguous but bounded classification, ranking, predicates, triagePredicate, choice, score, or refusalEvidence for policy, never permission by itself
Structured OutputsExtraction, explanation, or generated objects with a custom schemaSchema-conforming generated objectProposal requiring validation and policy
Function callingModel proposes which tool to call and with what argumentsTool name and argumentsApplication 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

FailureWhy it looks safeRequired response
Overlapping choicesOne value still winsRewrite taxonomy and test disagreement
Missing evidenceModel fills the patternSchema validation and refusal/human queue
Threshold copied from a demoConfidence appears preciseCalibrate on labeled production slices and costs
Dependent questions batchedAll answers return togetherStage requests after deterministic policy decisions
Refusal coerced to defaultPipeline stays greenPreserve refusal and stop or review
Cache survives policy changeLatency improvesVersion cache inputs and expire stale context
Distribution shiftAggregate accuracy remains stableSlice monitoring, drift alert, shadow recalibration
Score becomes permissionAutomation is fastAuthenticate and authorize in trusted code
API timeout or regional faultRetry eventually succeedsIdempotent queue, bounded retry, no unsafe default
Question changes without versionEndpoint and name stay the sameNew contract version, acceptance set, and threshold review

A four-stage production rollout

  1. 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.
  2. Build the acceptance set. Freeze representative labels, edge cases, missing evidence, adversarial wording, language and product slices, refusal expectations, and deterministic exclusions.
  3. 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.
  4. 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.
  5. Expand by evidence. Require stable slice metrics, acceptable reviewer capacity, tested rollback, cache-version controls, authorization separation, and incident drills before each increase.
  6. 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.