How to Use the OpenAI Decisions API ?

Call POST /v1/decisions on gpt-6-luna for $0.10 per 1M input tokens with no output charges. Working curl, Python and JavaScript, three question types on one ticket, image input, threshold tuning from labeled examples, and a full Apidog test and mock setup.

Ashley Innocent

Ashley Innocent

26 October 2026

How to Use the OpenAI Decisions API ?

Apidog for Enterprise

On-Premises Deploy

SSO & RBAC

SOC 2 Compliant

Explore Apidog Enterprise

To use the OpenAI Decisions API, send a POST request to https://api.openai.com/v1/decisions with "model": "gpt-6-luna", an input (text, images, JSON, or a mix), and a questions array where each question is a predicate, a choice, or a score. You get back typed answers with probabilities instead of text to parse. You pay $0.10 per 1M input tokens, $0.01 per 1M for cached input, and nothing for output. The endpoint went generally available on October 22, 2026 (OpenAI’s launch post).

This guide covers the first call in curl, Python and JavaScript, reading each answer type, three questions on one support ticket, image and JSON input, prompt caching, thresholds, and a testing setup in Apidog. For when to pick the endpoint at all, start with what is the OpenAI Decisions API.

button

Decisions API request at a glance

Field What it takes
model gpt-6-luna (the only model at GA)
input A string, or an array of messages; user content is a string or parts of type input_text, input_image and input_json
questions 1 to 400 per request
questions[].type predicate, choice, or score
questions[].instructions Required; the question in plain words (a string, or input_text / input_image parts)
questions[].name Optional; echoed back in the answer (null if omitted)
questions[].choices choice only; unique {value, description} objects, value a string or boolean
questions[].levels score only; 2 to 10 ordered {label, description} objects, lowest first, indices from 0
prompt_cache_key Optional; groups requests that share a cached prefix
safety_identifier Optional opaque end-user id, up to 128 chars

Source: the Decisions guide and the API changelog. There’s no temperature, stream, tools or text.format on this endpoint.

Get a key and make the first call

Create a key in the OpenAI dashboard (the OpenAI API key guide covers it), export it as OPENAI_API_KEY, and ask one yes/no question:

curl https://api.openai.com/v1/decisions \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-6-luna",
    "input": "The box arrived crushed and the screen is cracked.",
    "questions": [
      {"type": "predicate", "name": "damaged",
       "instructions": "Does the customer report a damaged item?"}
    ]
  }'

The response carries model, answers, and usage, with output_tokens at 0:

{
  "model": "gpt-6-luna",
  "answers": [
    {"type": "predicate", "name": "damaged", "probability": 0.95}
  ],
  "usage": {
    "input_tokens": 42,
    "input_tokens_details": {"cached_tokens": 0, "cache_write_tokens": 0},
    "output_tokens": 0,
    "output_tokens_details": {"reasoning_tokens": 0},
    "total_tokens": 42
  }
}

The same call in Python (SDK 3.26.0 or later):

from openai import OpenAI

client = OpenAI()  # reads OPENAI_API_KEY from the environment

decision = client.decisions.create(
    model="gpt-6-luna",
    input="The box arrived crushed and the screen is cracked.",
    questions=[
        {"type": "predicate", "name": "damaged",
         "instructions": "Does the customer report a damaged item?"}
    ],
)
print(decision.answers[0].probability)

And in JavaScript (SDK 7.30.0 or later):

import OpenAI from "openai";

const client = new OpenAI();

const decision = await client.decisions.create({
  model: "gpt-6-luna",
  input: "The box arrived crushed and the screen is cracked.",
  questions: [
    { type: "predicate", name: "damaged",
      instructions: "Does the customer report a damaged item?" },
  ],
});
console.log(decision.answers[0].probability);

Read the answer by type

Answers come back in the order you asked. Switch on type, because any question can come back as a refusal.

for a in decision.answers:
    if a.type == "refusal":
        send_to_review(a.name)
    elif a.type == "predicate":
        flag = a.probability > 0.9
    elif a.type == "choice":
        route = a.choice if a.confidence > 0.8 else "review"
    elif a.type == "score":
        priority = round(a.score)

Use choice for categories without an order, such as departments, and score for ordered levels, such as severity.

Three questions on one support ticket

Independent questions share one request and one input, and each can use a different type:

{
  "model": "gpt-6-luna",
  "input": "I was charged twice for my order.",
  "questions": [
    {"type": "predicate", "name": "refund_requested",
     "instructions": "Is the customer asking for money back?"},
    {"type": "choice", "name": "department",
     "instructions": "Which team should handle this ticket?",
     "choices": [
       {"value": "billing", "description": "Charges, refunds, invoices"},
       {"value": "technical", "description": "Bugs and errors in the product"},
       {"value": "shipping", "description": "Delivery and tracking"},
       {"value": "other", "description": "Anything else"}
     ]},
    {"type": "score", "name": "urgency",
     "instructions": "How urgent is this ticket?",
     "levels": [
       {"label": "low", "description": "No time pressure"},
       {"label": "medium", "description": "Needs a reply this week"},
       {"label": "high", "description": "Customer is blocked or losing money"}
     ]}
  ]
}

The choice values below are OpenAI’s guide values for this exact input; the predicate and score values are illustrative:

"answers": [
  {"type": "predicate", "name": "refund_requested", "probability": 0.88},
  {"type": "choice", "name": "department", "choice": "billing",
   "probabilities": [
     {"value": "billing", "probability": 0.95},
     {"value": "technical", "probability": 0.02},
     {"value": "shipping", "probability": 0.01},
     {"value": "other", "probability": 0.02}
   ],
   "confidence": 0.93},
  {"type": "score", "name": "urgency", "score": 1.6,
   "probabilities": [
     {"value": 0, "label": "low", "probability": 0.05},
     {"value": 1, "label": "medium", "probability": 0.30},
     {"value": 2, "label": "high", "probability": 0.65}
   ],
   "confidence": 0.65}
]

Include a fallback such as other, define score levels around observable criteria, and send a separate request for any decision that depends on an earlier answer.

Image and JSON input

Pass an image as an input_image part inside a user message. image_url takes an inline base64 data URL or a public HTTP(S) URL; both are documented at GA:

{
  "model": "gpt-6-luna",
  "input": [{
    "role": "user",
    "content": [
      {"type": "input_text", "text": "Photo attached to a return request."},
      {"type": "input_image", "image_url": "https://example.com/returns/8812.jpg"}
    ]
  }],
  "questions": [
    {"type": "predicate", "name": "visible_damage",
     "instructions": "Is the product visibly damaged?"}
  ]
}

file_id, file and audio inputs aren’t supported. Question instructions can carry images too, as an array of input_text and input_image parts with no role wrapper, for example a reference photo of an undamaged unit.

For structured records, send an input_json part instead of formatting a string. data takes an object or an array, and the part is allowed in user messages only:

"input": [{
  "role": "user",
  "content": [
    {"type": "input_json",
     "data": {"order_id": "A-1042", "charges": 2, "amount": 49.99}}
  ]
}]

Cut cost with prompt caching

Caching pays off when you ask many rounds of questions about the same long input, such as a contract. The shared prefix must be at least 1,024 tokens, and question content doesn’t count toward it. By default the cache breakpoint sits at the end of the shared input, so keep that text byte-identical across calls and tag related requests with the same prompt_cache_key:

{
  "model": "gpt-6-luna",
  "prompt_cache_key": "contract-4471",
  "input": "<the same 3,000-token contract text on every call>",
  "questions": [
    {"type": "predicate", "name": "auto_renews",
     "instructions": "Does the contract renew automatically?"}
  ]
}

Check usage.input_tokens_details. The first call shows cache_write_tokens, billed at $0.125 per 1M (30-minute) or $0.25 per 1M (12-hour). Later calls show cached_tokens, billed at $0.01 per 1M instead of $0.10. Both counts sit inside input_tokens. To place the breakpoint yourself, the guide documents prompt_cache_options.mode: "explicit" with a prompt_cache_breakpoint in the input.

Test the Decisions API in Apidog

OpenAI publishes no accuracy or calibration figures for the endpoint and tells you to set thresholds from labeled examples in your own application, weighing false positives against false negatives. Saved requests in Apidog make that tuning, and later regression checks, repeatable:

  1. Store the key as an environment variable. Add OPENAI_API_KEY as a secret variable (Apidog environments and secret variables shows the setup) and set the Authorization header to Bearer {{OPENAI_API_KEY}}.
  2. Save one request per question type. Create a POST to https://api.openai.com/v1/decisions, paste the choice question from the ticket example on its own, and save it. Duplicate it for predicate and score.
  3. Add JSONPath assertions. On the choice request: status is 200, $.answers[0].type equals choice, $.answers[0].choice equals billing, $.answers[0].confidence is greater than 0.8, and $.usage.output_tokens equals 0. For the damage predicate, assert $.answers[?(@.name=='damaged')].probability is greater than 0.9. A wording or model change now fails a test instead of misrouting tickets.
  4. Run it over labeled tickets. Build a test scenario from the saved request and attach a CSV with ticket_text and expected_department columns. Map {{ticket_text}} into input and assert $.answers[0].choice equals {{expected_department}}. The run report shows confidence for every row; the point below which every mis-route sits becomes your “route automatically” threshold.
  5. Mock the answers array for the frontend. Return a choice answer above and below your threshold, plus a refusal, so the review-queue path gets built before you spend an input token. Conditional mock responses in Apidog covers switching mocks on request content.
  6. Run the scenario in CI. Export an access token, then add a step to your pipeline:
apidog run --access-token "$APIDOG_ACCESS_TOKEN" \
  -t "$SCENARIO_ID" -e "$ENV_ID" -r cli,junit

A failed assertion fails the build, so a quiet drop in confidence is caught before deploy. For broader patterns, see testing LLM applications.

Handle errors and edge cases

FAQ

How much does the Decisions API cost? $0.10 per 1M input tokens on gpt-6-luna, $0.01 per 1M cached input, cache writes at $0.125 (30-minute) or $0.25 (12-hour) per 1M, and no output charge. A 500-token ticket with three questions costs 500 / 1,000,000 x $0.10 = $0.00005, so a million such tickets cost $50. Long-context input over 272K tokens is 2x, and regional processing adds 10%.

Is the Decisions API free? No. There’s no free Decisions tier; the GPT-6 Luna free routes post lists other ways to try the model.

How fast is it? OpenAI says up to 10x faster than GPT-6 Luna through the Responses API and publishes no absolute latency number. Box reports about 5x faster route selection in its own 30-case evaluation.

Which models work with the Decisions API? Only gpt-6-luna. It’s an endpoint on Luna, not a separate model. See what is GPT-6 Luna for the model itself.

When should I use Structured Outputs instead? When you need an object in your own JSON schema, such as extracted fields or a written explanation (OpenAI Structured Outputs covers that path), or function calling when the model should request a tool. The Decisions API vs Responses API post shows the same ticket done both ways.

How does it compare with Jev? Both return typed answers with probabilities and bill input only; Jev is text-only at $0.042 per 1M. The Decisions API vs Jev comparison has the full table.

Next step

Send the three-question ticket request, run it over 20 of your own labeled tickets, and see where confidence separates correct routes from wrong ones. Then download Apidog to keep the request, the CSV scenario and the assertions together, so today’s threshold gets re-checked on every deploy.

Explore more

Claude Code Subagents Now Use Less of Your Limit

Claude Code Subagents Now Use Less of Your Limit

Background subagents in Claude Code now take less of your usage limit. Here's who gets the change, what 99% and 5% mean, and how to cut subagent usage further.

6 November 2026

What is Gemini Omni 1.2 Flash?

What is Gemini Omni 1.2 Flash?

Gemini Omni 1.2 Flash is Google's GA video model: 15-second clips, about $0.07 per second at 720p, and a December 3 reroute of all 1.1 traffic. Here's what changed, what it costs, where to call it and what to retest.

6 November 2026

How to use Gemini Omni 1.2 Flash for free

How to use Gemini Omni 1.2 Flash for free

The Gemini API has no free tier for Omni 1.2, but Google Flow and Google Vids do cost $0. Here's what each route gives you and what to do when it runs out.

6 November 2026

Practice API Design-first in Apidog

Discover an easier way to build and use APIs

How to Use the OpenAI Decisions API ?