OpenAI Decisions API Guide: Fast Typed Routing, Confidence Thresholds, and Safer Agent Workflows
The OpenAI Decisions API turns text and images into fast, typed judgments your software can act on. This guide shows where it fits, how predicate, choice, and score answers work, and how to add thresholds, evaluation, fallbacks, and human review before a probability controls a real workflow.
OpenAI Decisions API: The Quick Answer
The OpenAI Decisions API is a specialized endpoint for questions whose possible answers are known before the request is sent. Your application supplies shared evidence, such as a support ticket, product description, incident report, or image, and defines one or more questions. The endpoint returns a typed answer: the probability that a condition is true, one selected option from a fixed set, or a score across ordered levels.
This is not a smaller chat interface. It does not write an email, explain its reasoning, call a tool, maintain a conversation, or generate an arbitrary JSON object. It is designed for the narrow moment between receiving messy input and choosing what the software should do next. That makes it useful for classification, routing, prioritization, triage, guardrails, and simple visual checks.
OpenAI released the endpoint in public beta with gpt-6-luna. The official guide says it can produce decisions about ten times faster than using the same model through the Responses API for this pattern. The published price is $0.10 per million input tokens, with no output-token, cache-read, or cache-write charge. Those numbers are attractive, but speed and price do not remove the need for testing. A fast wrong route is still wrong.
The most important production lesson is to separate model output from business policy. A result with 0.72 probability is evidence. It is not automatically permission to refund an order, block a user, approve a medical claim, publish content, or merge code. Define policy thresholds, safe fallbacks, audit logs, and review paths around it.
Why the Decisions API Matters for Agent Builders
Many AI systems spend expensive model time generating prose that the application immediately discards. A router may ask a model to return a sentence such as “send this request to billing,” parse that sentence, and then start the real workflow. The task was never generation. It was selection.
The Decisions API makes that boundary explicit. If a customer message must go to billing, account access, technical support, or a general queue, provide those choices. If a quality-control photo must be checked for visible damage, ask a predicate question. If an incident must be scored from cosmetic to fully blocked, define an ordered rubric. The output is already shaped for software.
This fits a broader move toward specialized components in agent systems. A capable agent may still use the OpenAI Agents API for durable cloud work, while a Decision call handles the small gate before a costly run begins. Teams already studying OpenAI Codex pricing and usage limits will recognize the pattern: put the lightest reliable component at each step, then spend stronger-model capacity only where it creates value.
The feature is especially relevant for high-volume workflows: support inboxes, trust and safety queues, document intake, lead qualification, moderation pre-filters, bug triage, model selection, and agent handoffs. The gain is not only lower per-call cost. Typed outputs reduce parsing code, narrow the model’s freedom, and make the decision surface easier to test.
Still, the endpoint is in beta. Treat its schema, availability, and behavior as a dependency that can evolve. Pin compatible SDK versions, handle API errors explicitly, log the model and question definition used for every result, and keep a deterministic fallback for business-critical systems.
How the OpenAI Decisions API Works
An official Decisions request has three main parts: model, input, and questions. The model is currently gpt-6-luna. The input is shared evidence, either a text string or user messages containing text and images. Questions describe the judgments you want, including a unique name, a type, instructions, and any options or levels.
The response returns an answers array in the same order as the questions. Unique names matter because a production service should match results by stable identifiers rather than by presentation text. Any question may return a refusal; other questions in the same request can still receive answers, so code must handle each result independently.
The official endpoint reference allows between one and 200 questions in one call and up to 128 images across the messages. Image inputs can be public HTTP(S) URLs or base64 data URLs. Files, audio, tools, and item references are not supported by this endpoint. Those limits are useful, but they should not be a target. A giant request with dozens of loosely related questions is harder to evaluate, version, and debug than a focused decision contract.
Independent questions can share input
If several questions inspect the same evidence independently, combine them. A product photo could be checked for visible damage and separately classified by product category. Sharing the input avoids sending the same evidence in multiple Decision requests and gives your service one response to log.
Dependent questions need separate requests
If question B depends on answer A, do not pretend they are independent. First determine whether damage is visible. Then, only if the probability and policy cross your threshold, send a second request to classify the damage. This makes the dependency visible in code, lets you apply a checkpoint, and prevents a later question from being evaluated on an assumption the first answer did not support.
Observable criteria beat vague intent
“Is this customer valuable?” is vague, subjective, and likely to encode hidden bias. “Does this message describe a renewal scheduled within seven days?” is observable. Strong questions describe evidence the model can inspect. Strong choices have distinct meanings. Strong score levels explain what changes from one level to the next.
Predicate, Choice, and Score: Choose the Right Decision Type
The API supports three question shapes. Selecting the right one is more important than clever wording because each type creates a different contract between the model and your code.
| Type | What it returns | Use it for | Common mistake |
|---|---|---|---|
| Predicate | Probability from 0 to 1 that a statement is true | Visible damage, policy match, relevance, duplication, requested cancellation | Treating the probability as a universal confidence score without calibration |
| Choice | One supplied option, probability per option, and confidence | Department routing, content category, model selection, document type | Using overlapping options or omitting an “other” path |
| Score | Probability distribution over ordered levels plus a weighted score | Severity, urgency, quality, risk tiers, review priority | Assuming the numeric result is an objective measurement |
Predicate: answer one testable condition
A predicate is ideal when policy can be expressed as one observable yes-or-no condition. The model returns the estimated probability that it is true. Your code then applies a threshold. For a product photo, the question might ask whether the item has a crack, tear, or dent while explicitly ignoring packaging damage and shadows.
Do not combine several conditions into one vague predicate. “Is this request suspicious, urgent, and abusive?” hides three different concerns. Ask separate questions so you can see which signal changed and tune each policy independently.
Choice: route among distinct categories
A choice question selects one supplied value and returns probabilities for the options. Write the description for each option as a routing rule. “Billing” is a label; “payments, invoices, refunds, and duplicate charges” is usable guidance. Add an other or needs_review choice whenever the real world can fall outside your taxonomy.
Choices should be mutually exclusive enough for action. If both “account” and “subscription” could include the same cancellation message, the router is being asked to invent a boundary. Refine the taxonomy or move the overlap into a second-stage decision.
Score: place evidence on an ordered rubric
A score uses ordered levels, such as cosmetic, workaround available, and fully blocked. The returned score is a probability-weighted average of the level indices, so it may fall between levels. That does not mean the feature measured a natural continuous quantity. It summarizes uncertainty across the rubric you supplied.
Use score when order is meaningful. Do not use it for unordered categories such as departments or document types. Adjacent levels need distinct criteria: describe exactly what separates “minor” from “major,” and test borderline examples before automation depends on that boundary.
OpenAI Decisions API vs Responses API, Structured Outputs, and Rules
The fastest way to choose an architecture is to begin with the output your application truly needs. If it needs a typed judgment from a finite set, Decisions is a candidate. If it needs prose, arbitrary fields, tools, streaming, or conversation state, use the Responses API. If a deterministic rule can solve the problem reliably, use the rule first.
| Need | Best starting point | Why |
|---|---|---|
| Yes/no probability, fixed category, or ordered rubric | Decisions API | Typed answers, narrow contract, fast decision path |
| Generated explanation or custom JSON object | Responses API with Structured Outputs | Your schema can include extracted fields and written content |
| Model should call a tool with arguments | Responses API with function calling | The model can request an action; Decisions cannot call tools |
| Long-running agent with state and multiple tools | Responses or Agents API | Conversation, tools, background execution, and orchestration matter |
| Exact match, numeric limit, allowlist, or known rule | Normal code | Cheaper, faster, predictable, and easier to audit |
OpenAI’s Decisions guide explicitly points developers to Structured Outputs when they need an object following their own JSON schema and to function calling when a model must request a tool. Trying to force Decisions to become a general generator defeats the product’s purpose.
Watch for duplicate processing
A common design sends a large document to Decisions, then sends the same document to Responses for generation. These are separate calls and should be budgeted as separate processing steps. Community discussion has raised questions about cache behavior across the two paths. The safe assumption is that a Decision call does not make a later Responses call free. Measure actual usage rather than designing around an undocumented shared-cache expectation.
A better pipeline may extract or store the original evidence once, ask a compact decision question, and pass only the relevant excerpt or stable reference into the next step. For related cost-control patterns, see our guide to routing work to lower-cost models without breaking quality.
Use rules before models
If an invoice total above a fixed amount must go to review, normal code should enforce the threshold. Use AI for semantic ambiguity: understanding whether a complaint describes a duplicate charge, whether an image appears damaged, or whether a free-form incident report matches a severity rubric. A rules-first cascade reduces cost and makes the exceptions easier to inspect.
Build a Safer Decisions API Router
The following JavaScript example shows the core pattern for routing a support message. It includes distinct categories and a fallback option. It does not automatically execute a refund or close a ticket. It returns a signal to policy code.
import OpenAI from "openai";
const client = new OpenAI();
const decision = await client.decisions.create({
model: "gpt-6-luna",
input: "I was charged twice for my order and need the extra payment returned.",
questions: [{
type: "choice",
name: "support_queue",
instructions: "Which team should handle this request?",
choices: [
{ value: "billing", description: "Charges, invoices, payments, and refunds." },
{ value: "technical", description: "Product behavior, errors, and outages." },
{ value: "account", description: "Login, identity, access, and security." },
{ value: "other", description: "Anything outside the listed categories." }
]
}]
});
const answer = decision.answers[0];
if (answer.type === "refusal") {
routeToHumanReview("model_refusal");
} else if (answer.type === "choice") {
applyRoutingPolicy(answer.choice, answer.confidence, answer.probabilities);
}For current SDK minimum versions and examples in Python, JavaScript, Go, Ruby, and Java, use the official documentation rather than copying old snippets. The beta requires newer SDK resources than an older OpenAI package may contain.
Separate the question contract from runtime code
Store question definitions as versioned configuration. Give each one an owner, purpose, input contract, allowed outputs, threshold policy, and evaluation set. A wording change can alter routing behavior even when application code does not change. Treat it like a code change: review it, test it, deploy it gradually, and keep the previous version available for comparison.
Preserve an input identifier
Every item should carry a stable identifier through Decision calls, retries, queues, and human review. The endpoint evaluates evidence; your application owns idempotency. If a timeout occurs after the provider accepted a request, retrying must not cause the same ticket to be routed twice or trigger two downstream actions.
Fail closed for sensitive actions
If a response is malformed, missing, refused, timed out, or below threshold, do not silently choose the first category. Send the item to a safe queue or apply a conservative default. “Fail closed” does not always mean block the user. It means choose the outcome with the lowest irreversible cost.
Set Confidence Thresholds and an Abstain Path
The most useful gap in early Decisions API coverage is threshold design. OpenAI’s documentation recommends using labeled examples from your application and choosing thresholds based on the cost of false positives and false negatives. That is the right principle, but teams still need an operating method.
Start with a representative dataset of real inputs and reviewed outcomes. Keep a separate holdout set that prompt authors do not tune against. Run the frozen question definition over the data and record the returned result, probabilities, confidence, latency, token usage, and any refusal. Then sweep candidate thresholds and measure what changes.
Use two thresholds when uncertainty matters
A single threshold forces every item into yes or no. A two-threshold policy creates an abstain band. For a predicate, a probability at or above the upper threshold can follow the positive route, while a probability at or below the lower threshold follows the negative route. Values between them go to review.
For example, a low-risk content tagger might accept more automation than an account-security gate. The correct thresholds depend on error cost, prevalence, staffing, and the quality of your labeled data. Do not copy a threshold from a tutorial and call it calibrated.
This helper is deliberately not a numeric threshold calculator. Without your validation labels and error costs, a precise threshold would be false precision. Its purpose is to show which conditions demand a wider review band and a slower rollout.
Different routes can need different thresholds
A billing category may be easy to recognize, while account security may require stricter review. One global confidence threshold can hide those differences. Measure per-class precision and recall, and give sensitive categories their own policy.
Confidence is not the same as correctness
A high-confidence wrong answer is possible. Confidence can also shift when inputs, question wording, option descriptions, or the underlying model change. Calibration is an empirical property of a model-question-domain combination. It must be measured again when that combination changes.
How to Evaluate the OpenAI Decisions API Before Production
A useful evaluation tests the complete decision contract, not only aggregate accuracy. The system includes input preparation, question wording, option definitions, thresholds, retries, policy rules, and review capacity. Each part can fail.
1. Define the consequence. Write what happens after each result and what a false positive or false negative costs. If nobody can explain the consequence, the decision is not ready for automation.
2. Create a labeled dataset. Sample the inputs your application actually receives, including routine cases, edge cases, low-quality images, multilingual messages, adversarial content, and examples that fit no category.
3. Freeze a holdout set. Tune instructions and option definitions on development examples, then evaluate once on untouched examples. Repeatedly tuning against the test set produces a flattering but unreliable score.
4. Measure by class. Overall accuracy can hide a rare, costly failure. Track confusion matrices, precision, recall, review rate, refusal rate, and the share of items in the abstain band for every important class.
5. Test stability. Repeat requests, vary harmless formatting, shuffle choice order, and test equivalent wording. Material changes reveal brittleness that a single pass misses.
6. Measure latency percentiles. Averages hide tail behavior. Record p50, p95, and p99 from the regions and payload sizes your users will encounter.
7. Shadow first. Run Decisions beside the existing process without controlling outcomes. Compare results, inspect disagreements, and learn how much review work the proposed thresholds create.
8. Roll out by reversibility. Begin with low-impact routing, sampling, or prioritization. Expand only when monitoring shows that errors are understood and recoverable.
Check probability calibration
If the model assigns about 0.8 probability to many predicate examples, roughly 80 percent of those examples should be positive for the probabilities to be well calibrated in your domain. Group predictions into bins, compare predicted and observed rates, and use enough examples to avoid reading noise as signal. Calibration may differ across categories and input types.
Test option order and taxonomy boundaries
Choice systems can be sensitive to how categories are described and ordered. Shuffle options during evaluation and compare results. Add examples that sit between neighboring categories. If a category wins only because its description is broader than the others, fix the taxonomy before tuning the prompt.
Test direct images against extracted text
The API supports image evidence, and OpenAI provides an official visible-damage example. Recent community discussion also reports cases where a textual representation performed better than raw spatial input. Do not generalize from one anecdote. For your use case, compare direct images, OCR or structured observations, and combined inputs on the same labeled set. Measure quality, latency, cost, and failure modes.
Monitor drift after launch
Products change, users invent new language, fraud adapts, and support categories evolve. Sample automated decisions for ongoing review. Track changes in input distribution, option probabilities, review rate, refusal rate, and downstream corrections. A rising “other” rate often signals that the taxonomy no longer fits reality.
If you already measure AI adoption or cost, the monitoring approach in our AI usage metrics API guide is a useful companion: instrument the workflow before debating whether the model is saving time.
Production Patterns That Make Typed Decisions Safer
Rules, then Decision, then generator
Start with deterministic checks for known conditions. Send only ambiguous semantic cases to Decisions. If the result clears policy, call a generator or agent for the work that actually needs language, tools, or multi-step reasoning. This cascade keeps the expensive stage focused.
Decision with an explicit review queue
Every router should have a route for inputs that do not fit, fall below threshold, or return a refusal. Give reviewers the original evidence, model version, question version, probability distribution, and prior actions. A review queue without context simply moves debugging from code to people.
Decision as an advisory signal
For high-impact workflows, log the result as a recommendation while a human makes the final call. The collected decisions and outcomes become labeled data for later evaluation. Advisory deployment is not wasted effort; it is how a team learns whether automation is deserved.
Multi-signal policy
Combine a model signal with deterministic business facts. A support ticket might enter priority review only when its severity score is high and the affected account has an active production contract. The model interprets language; the database supplies facts. Keeping these roles separate improves auditability.
Versioned decision contracts
Log a hash or version for the question definition, choices, score levels, preprocessing logic, threshold policy, and model. When results drift, you need to know which component changed. This discipline mirrors safe agent configuration practices in our OpenAI AgentKit guide.
Good fits
✓ Finite, testable answer space
✓ High-volume semantic routing
✓ Reversible or reviewed actions
✓ Representative labeled examples available
✓ Clear fallback when confidence is low
Poor fits
× Open-ended writing or explanation
× Tool calling or conversational state
× Categories that overlap by design
× Irreversible action without review
× No way to verify the intended outcome
OpenAI Decisions API Pricing, Limits, and Availability
According to OpenAI’s current documentation, Decisions is in public beta and uses gpt-6-luna. Input costs $0.10 per million tokens. The endpoint charges no output tokens, cache reads, or cache writes. Regional processing premiums and long-context input multipliers can still apply, so the headline input rate is not the only possible cost.
The endpoint currently supports one to 200 questions and up to 128 images per request. It accepts text and images, but not files, audio, tools, or item references. The practical design limit will often be lower: focused calls are easier to evaluate, and large image payloads still contribute to input usage.
OpenAI states that the Decisions API supports Zero Data Retention and eligible HIPAA use, with data residency and regional processing in the United States and Europe, subject to account configuration, agreements, and limitations. Read the current OpenAI data controls documentation before making compliance claims about your application.
Estimate cost with real payloads
Do not multiply the advertised token rate by request count alone. Log the input token usage for representative text and images, regional settings, long-context cases, retries, shadow traffic, and any subsequent Responses call. Then calculate cost per completed business outcome, including human review. The cheapest model call can be expensive if poor routing creates rework.
Pin and monitor the beta
Use the minimum SDK versions listed in the official guide or later. Pin a tested range in production, monitor the OpenAI API changelog, and test upgrades in staging. Handle rate limits and beta changes as normal external dependency risks.
For agent integration, the OpenAI Agents SDK model guide shows Decisions used alongside an agent run rather than as an Agents SDK model implementation. That boundary is healthy: ask Decisions to gate, route, or score; let the agent handle tools and multi-step work.
Security, Privacy, and High-Impact Use
A decision endpoint can look safer than a generative model because the answer space is constrained. That is only one layer of safety. The input may still contain personal data, trade secrets, regulated information, adversarial instructions, or untrusted images. Minimize evidence before sending it and avoid including fields the question does not need.
Do not treat the model’s probability as authorization. Enforce permissions and policy in normal code. A decision that an email “looks like a manager request” must not grant manager privileges. A choice that routes a task to an administrative agent must not silently expand that agent’s tools. The same principle applies to the always-on systems described in our OpenAI Dots guide: delegation should preserve visible permission boundaries.
Log enough to audit outcomes without retaining unnecessary sensitive content. Depending on your risk model, store stable item identifiers, question version, answer distribution, threshold result, downstream action, reviewer correction, and timestamps. Separate evaluation logs from raw customer content when possible.
For moderation, employment, lending, healthcare, identity, and account enforcement, consult qualified legal, privacy, and domain experts. This guide explains engineering patterns; it does not turn a general model probability into a compliant decision system.
Deployment Checklist
✓ The output can be expressed as predicate, choice, or ordered score.
✓ Every choice is distinct, and an “other” or review path exists.
✓ Questions describe observable evidence instead of subjective intent.
✓ A representative labeled dataset and untouched holdout set exist.
✓ Thresholds reflect false-positive and false-negative costs.
✓ Refusals, timeouts, malformed responses, and low confidence fail safely.
✓ Stable item IDs make retries idempotent.
✓ Question, threshold, preprocessing, and model versions are logged.
✓ Shadow testing measured quality, p50/p95/p99 latency, and review volume.
✓ Monitoring detects drift, rising “other” rates, and reviewer corrections.
✓ Permissions and irreversible actions remain in deterministic policy code.
✓ Current pricing, residency, retention, and compliance settings were verified.
If a workflow runs on a schedule or in the background, borrow the approval and monitoring discipline from our ChatGPT Work scheduled tasks guide. Automation should be quiet when nothing meaningful changed, loud when review is required, and clear about what it changed.
Final Recommendation
Use the OpenAI Decisions API when your application needs a fast semantic judgment from a finite answer space. It is a strong fit for routing, triage, prioritization, image checks, and agent gates. It is not a replacement for the Responses API, tools, deterministic rules, or human judgment.
Begin with one narrow, reversible workflow. Define a decision contract, create labeled examples, add an explicit fallback, and run it in shadow mode. Measure per-class errors, probability calibration, latency percentiles, cost per completed outcome, and the amount of human review generated. Only then allow high-confidence results to automate a low-impact action.
The endpoint’s biggest advantage is not that it lets AI make more decisions. It lets developers make the decision boundary visible. The input, allowed answers, probability distribution, confidence policy, and fallback can all be inspected. Use that structure to build a system that knows when to route, when to ask a stronger model, and when to stop and let a person decide.
For the broader desktop-versus-agent workflow context, continue with our ChatGPT Work and Codex comparison. It helps separate quick conversational help, long-running delegated work, and the narrow routing layer Decisions now fills.
Sources and Further Reading
- OpenAI Decisions endpoint reference
- OpenAI Agents SDK model guidance
- Recent r/OpenAI discussion about the public beta
- Recent n8n discussion about thresholds, routing, and retries
Product behavior, pricing, limits, and beta availability can change. Verify the official documentation and your account settings before deployment.
FAQ: OpenAI Decisions API
What is the OpenAI Decisions API?
It is a specialized endpoint that evaluates text, images, or both and returns a typed judgment: a predicate probability, one choice from supplied options, or a score over ordered levels. It is intended for classification, routing, prioritization, and similar finite-answer tasks.
How is the Decisions API different from the Responses API?
Decisions returns constrained judgments from a finite answer space. Responses can generate text or custom JSON, call tools, stream output, and maintain richer state. Use Decisions for a narrow gate or router and Responses for generation or agent work.
What do predicate, choice, and score mean?
Predicate estimates whether one condition is true. Choice selects one unordered option and returns probabilities. Score evaluates evidence against ordered levels and returns a probability-weighted position across them.
How should I set a confidence threshold?
Run the frozen question on representative labeled data, measure false positives and false negatives at different thresholds, and choose a policy based on error cost. For sensitive cases, use upper and lower thresholds with a human-review band between them.
Can the Decisions API analyze images?
Yes. It accepts public image URLs or base64 data URLs alongside text. Test the exact image types, quality, detail level, and ambiguity your application will receive instead of assuming a demo result will transfer.
Can it call tools, accept files, or maintain a conversation?
No. The endpoint does not support tools, files, audio, or item references. Use the Responses API or an agent workflow when you need those capabilities.
How much does the OpenAI Decisions API cost?
OpenAI currently lists GPT-6 Luna Decisions input at $0.10 per million tokens, with no output-token, cache-read, or cache-write charges. Regional processing and long-context multipliers may apply.
Can I ask several questions in one request?
Yes, for independent questions over shared evidence. If one decision depends on a previous answer, make separate calls so your application can apply policy between them.
What if none of the choice options fits?
Include an explicit “other” or “needs review” option. Also route low-confidence, refused, missing, or malformed results to a safe fallback instead of silently selecting a category.
Can I use Decisions with the OpenAI Agents SDK?
Yes, alongside an agent run. The official Agents SDK guidance calls the native Decisions client for classification, guardrails, approval callbacks, or model selection; Decisions itself is not an Agents SDK model interface.
Are the returned probabilities automatically calibrated?
Do not assume they are calibrated for your domain. Compare predicted probabilities with observed outcomes on representative labeled data and repeat the test when the model, question, choices, preprocessing, or traffic changes.
When should a human review the result?
Use human review when confidence falls inside an abstain band, the model refuses, evidence is incomplete, the category has high error cost, or the resulting action affects money, access, safety, rights, or other high-impact outcomes.
Post a Comment