OpenAI Decisions API Explained: How It Works and When Not to Use It

OpenAI Decisions API Explained: How It Works and When Not to Use It

01Introduction

The OpenAI Decisions API answers questions with a decision instead of a paragraph.

You give it some input, like a customer message, an image or a piece of JSON. You ask it a question, like "Is this a billing problem?" It answers with a number or one of the options you gave it. It doesn't write text.

OpenAI launched it in public beta on October 6, 2026, and made it generally available on October 22, 2026. It runs on the gpt-6-luna model and is about 10 times faster than a normal model call.

Here's how it works, what it costs, and when you shouldn't use it.

02What is it for?

Apps and AI agents make lots of small decisions every second:

• Which team should handle this support ticket?
• Is this message spam?
• How urgent is this request?
• Which tool should the agent use next?

Before, you had to ask a full AI model and parse its answer. The Decisions API is built only for these quick choices, so it's faster, cheaper and easier to work with.

03How it works

You send three things:

1. The model: gpt-6-luna
2. The input: the text, image or data to look at
3. Your questions: up to 400 in one request

Here's a simple example. We ask if a customer is describing a duplicate charge:

from openai import OpenAI

client = OpenAI()
decision = client.decisions.create(
    model="gpt-6-luna",
    input="I was charged twice for my order.",
    questions=[{
        "type": "predicate",
        "name": "duplicate_charge",
        "instructions": "Does the message describe a duplicate charge?",
    }],
)

And the answer:

{"answers": [{"type": "predicate", "name": "duplicate_charge", "probability": 0.92}]}

The model is 92% sure it's a duplicate charge. Your code decides what to do with that.

04Three types of answers

You can ask three kinds of questions:

• Yes or no (predicate): "Is this spam?" You get back a probability, like 0.92.
• Pick one (choice): "Which team handles this: billing, shipping or tech?" You get back one of your options.
• Rate it (score): "How urgent is this, from low to critical?" You get back a position on your scale.

If the model can't answer a question, it says so with a "refusal", so your code always gets a clear response.

Example: route a support ticket

"Pick one" is the most common use. Here we send a ticket to the right team:

decision = client.decisions.create(
    model="gpt-6-luna",
    input="My package was supposed to arrive Monday and it's still not here.",
    questions=[{
        "type": "choice",
        "name": "team",
        "instructions": "Which team should handle this ticket?",
        "choices": [
            {"value": "billing", "description": "Payments, refunds, invoices"},
            {"value": "shipping", "description": "Deliveries, tracking, returns"},
            {"value": "tech", "description": "Login problems, bugs, errors"},
        ],
    }],
)

The answer names one of your options, plus how sure the model is about each one. Your code reads choice and sends the ticket to shipping. If the confidence is low, you can send it to a person instead.

05What does it cost?

• $0.10 per million input tokens, and $0.01 if the input is cached.
• Output is free. The answers are tiny, so you only pay for what you send.

In real numbers: a support ticket plus the question is about 250 tokens. Routing 1,000 tickets is 250,000 tokens, which costs about $0.025. That's two and a half cents.

06Why not use Structured Outputs instead?

You can already make a normal model pick from a list, using Structured Outputs and a JSON schema. So why a separate API? Three reasons:

• It's faster. OpenAI says the Decisions API is about 10 times faster than the Responses API. That matters when a user is waiting or an agent makes dozens of choices in a row.
• You get the probabilities. Structured Outputs gives you an answer. The Decisions API also tells you how sure it is about every option, so you can set your own thresholds, like "only auto-route above 80%".
• There's no output charge. Structured Outputs bills output tokens. For a one-word answer that's small, but at millions of decisions it adds up.

Use Structured Outputs when you need the model to write or extract something. Use the Decisions API when you only need it to choose.

07OpenAI isn't the only one

Two similar "decision models" launched in the same few weeks:

They all work the same way: they score the options you give them instead of writing text.

08When you should NOT use it

The Decisions API gives you a probability, its best guess. That's perfect for judgment calls, like whether a message sounds angry or which team should handle a ticket.

But some questions aren't judgment calls. They have one correct answer that you can look up:

• Can this email address receive mail? A quick mail server check knows for sure.
• Is this IBAN correct? The checksum is maths, and the bank is in a registry.
• Is this EU VAT number real? The EU's official database knows.

If you ask an AI model these questions, you're adding a chance of being wrong to something that never needed one.

Developers testing the beta noticed something else: the "pick one" answers can sound more sure than they should. In one test with a coin weighted 70/30, the "pick one" format chose heads 98% of the time. The yes-or-no format got it right at about 70%. That's fine for routing tickets. It's not fine for payments.

Compare that with a validation API. We sent a throwaway email address to ApyHub's Email Validation API:

Request:  {"email": "[email protected]"}
Response: {"data": false}

No probability, just "no". The domain is a known throwaway provider, and the answer will be the same every time.

A simple rule to follow

• Can you look the answer up? Use an API or a rule.
• Is it about meaning or tone? Use a decision model.
• Is money or access involved? Always double-check in your own code.

The best setups use both. For example, the Decisions API sends a ticket to the billing team, then an IBAN validation API checks the bank details before anyone sends a refund.

09Give your AI agent both

If you're building an AI agent, use the Decisions API for judgment calls. For facts, ApyHub MCP gives Claude, ChatGPT, Cursor or Mistral Le Chat ready-made tools from the ApyHub catalog, including email, phone, IBAN and VAT checks.

The agent asks a model when it needs an opinion, and calls a tool when it needs a fact.

Want to try both side by side first? Save the requests in Voiden, a free, open-source API client that keeps them as files in your project.

Browse the validation APIs →

10Conclusion

The OpenAI Decisions API is a fast, cheap way to make small decisions in your app: yes or no, pick one, or rate it. Use it for judgment calls like routing and tagging. For facts like email, bank and VAT checks, use a validation API that gives the same correct answer every time.

Start free on ApyHub, no card required →

11FAQ

What is the OpenAI Decisions API?

It's an OpenAI tool that answers questions with a probability, a choice or a score instead of text. It runs on gpt-6-luna.

How much does it cost?

$0.10 per million input tokens. Output is free.

Is it available to everyone?

Yes. It's been generally available since October 22, 2026.

How many questions can I ask at once?

Up to 400 per request.

Is it better than Jev?

It depends. The Decisions API handles images and JSON. Jev is cheaper for text. Early community tests showed mixed results between the two.

Should I use it to check emails or payment details?

No. Those have one correct answer you can look up. Use a validation API instead.

12About ApyHub

ApyHub is a curated API catalog and the trusted operational layer between your application and the services it depends on. One subscription, billed in atoms, covers the whole catalog of over 1,500 endpoints and capabilities, and it keeps growing. Every service is evaluated before it is listed and carries machine-readable certification covering GDPR, SOC 2 and ISO 27001. Every endpoint is MCP-ready by default. ApyHub runs dedicated EU and US regions and serves more than 65,000 developer workspaces every month. Start on the free tier with no card, or publish your own API on ApyHub.

13Sources

• OpenAI, Decisions guide
• OpenAI Developer Community, Decisions API is now generally available (October 22, 2026) and Public Beta announcement (October 6, 2026)
• OpenAI, DevDay 2026 recap
• AI Weekly, Amazon ships Strands Decider 2B, an open-source Jev rival (October 1, 2026)