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.
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.
predicatereturnsprobability, an estimate from 0 to 1 that the condition is true.choicereturnschoice(the winningvalue),probabilitiesas an array of{value, probability}objects, andconfidence.scorereturnsscore,probabilitiesas{value, label, probability}objects (valueis the 0-based level index), andconfidence. The score is the probability-weighted average of the indices, so 1.1 means “between level 1 and level 2, close to 1”.refusalreturns onlytypeandname. Other questions in the same request can still receive answers.
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:
- Store the key as an environment variable. Add
OPENAI_API_KEYas a secret variable (Apidog environments and secret variables shows the setup) and set theAuthorizationheader toBearer {{OPENAI_API_KEY}}. - Save one request per question type. Create a POST to
https://api.openai.com/v1/decisions, paste thechoicequestion from the ticket example on its own, and save it. Duplicate it for predicate and score. - Add JSONPath assertions. On the choice request: status is 200,
$.answers[0].typeequalschoice,$.answers[0].choiceequalsbilling,$.answers[0].confidenceis greater than 0.8, and$.usage.output_tokensequals 0. For the damage predicate, assert$.answers[?(@.name=='damaged')].probabilityis greater than 0.9. A wording or model change now fails a test instead of misrouting tickets. - Run it over labeled tickets. Build a test scenario from the saved request and attach a CSV with
ticket_textandexpected_departmentcolumns. Map{{ticket_text}}intoinputand assert$.answers[0].choiceequals{{expected_department}}. The run report showsconfidencefor every row; the point below which every mis-route sits becomes your “route automatically” threshold. - Mock the
answersarray for the frontend. Return achoiceanswer above and below your threshold, plus arefusal, so the review-queue path gets built before you spend an input token. Conditional mock responses in Apidog covers switching mocks on request content. - 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
- 429 rate limited. No Decisions-specific limits are published; check Settings > Organization > Limits. Back off exponentially and honor a
Retry-Afterheader when present. The rate limit exceeded guide has a retry wrapper. - Refusal answers. Treat
type: "refusal"as a routing outcome, not an exception: send that ticket to a human and keep the other answers.
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.



