Skip to content
For the complete documentation index, see llms.txt. Markdown versions of documentation pages are available by appending .md to the page URL.
Primary navigation

Suggested
Overview Models Agents Tools Audio & voice Production API reference

Create a decision

POST
/decisions

Use this endpoint to quickly answer classification or scoring questions about some input. You can ask multiple questions in one request.

Body Parameters
JSON
input: string or array of DecisionInputMessage or object { content, role, type } or object { content, role, type } or 2 more

The input to evaluate for every question. Provide a text string or an ordered array of messages, function calls and outputs, or custom tool calls and outputs. Each tool output must identify a matching call by call ID.

One of the following:
string
array of DecisionInputUserMessage { content, role, type } or DecisionInputDeveloperMessage { content, role, type } or DecisionInputSystemMessage { content, role, type } or 5 more
One of the following:
DecisionInputUserMessage object { content, role, type }

A user message containing input text, images, or JSON.

content: string or array of DecisionInputPart

A text string or an ordered list of text, image, and JSON parts.

One of the following:
string
Parts = array of DecisionInputPart
One of the following:
DecisionInputText object { text, type, prompt_cache_breakpoint }
text: string
minLength0
maxLength10485760
type: "input_text"
prompt_cache_breakpoint: optional object { mode } or null

Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request’s prompt_cache_options.ttl; the boundary is not rounded to a token block.

mode: "explicit"

The breakpoint mode. Always explicit.

DecisionInputImage object { image_url, type, detail, prompt_cache_breakpoint }

An image provided as a base64 data URL or a publicly accessible HTTP(S) URL. File IDs are not supported.

image_url: string

A base64-encoded image in a data URL or a publicly accessible HTTP(S) image URL.

minLength0
maxLength1073741824
type: "input_image"
detail: optional "low" or "high" or "auto" or "original" or null

The image detail level, using the selected model’s image profile. Defaults to auto.

One of the following:
"low"
"high"
"auto"
"original"
prompt_cache_breakpoint: optional object { mode } or null

Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request’s prompt_cache_options.ttl; the boundary is not rounded to a token block.

mode: "explicit"

The breakpoint mode. Always explicit.

DecisionInputJSON object { data, type }

A JSON object or an array of objects rendered as text. Nested values may be any JSON value. Limited to 32 container levels, 10,000 values, and 256 KiB of compact UTF-8 JSON.

data: map[unknown] or array of map[unknown]
One of the following:
map[unknown]
array of map[unknown]
type: "input_json"
role: "user"
type: optional "message"
DecisionInputDeveloperMessage object { content, role, type }

A developer message containing input text.

content: string or array of DecisionInputText { text, type, prompt_cache_breakpoint }

A text string or an ordered list of input text parts.

One of the following:
string
Parts = array of DecisionInputText { text, type, prompt_cache_breakpoint }
text: string
minLength0
maxLength10485760
type: "input_text"
prompt_cache_breakpoint: optional object { mode } or null

Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request’s prompt_cache_options.ttl; the boundary is not rounded to a token block.

mode: "explicit"

The breakpoint mode. Always explicit.

role: "developer"
type: optional "message"
DecisionInputSystemMessage object { content, role, type }

A system message containing input text.

content: string or array of DecisionInputText { text, type, prompt_cache_breakpoint }

A text string or an ordered list of input text parts.

One of the following:
string
Parts = array of DecisionInputText { text, type, prompt_cache_breakpoint }
text: string
minLength0
maxLength10485760
type: "input_text"
prompt_cache_breakpoint: optional object { mode } or null

Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request’s prompt_cache_options.ttl; the boundary is not rounded to a token block.

mode: "explicit"

The breakpoint mode. Always explicit.

role: "system"
type: optional "message"
DecisionInputAssistantMessage object { content, role, phase, type }

An assistant message containing output text or refusals.

content: string or array of OutputText { text, type } or Refusal { refusal, type }

A text string or an ordered list of output text and refusal parts.

One of the following:
string
Parts = array of OutputText { text, type } or Refusal { refusal, type }
One of the following:
OutputText object { text, type }
text: string
minLength0
maxLength10485760
type: "output_text"
Refusal object { refusal, type }
refusal: string
minLength0
maxLength10485760
type: "refusal"
role: "assistant"
phase: optional "commentary" or "final_answer" or null

The phase of an assistant message.

One of the following:
"commentary"
"final_answer"
type: optional "message"
FunctionCall object { arguments, call_id, name, 4 more }
arguments: string
minLength0
maxLength1048576
call_id: string
minLength1
maxLength64
name: string
minLength1
maxLength128
type: "function_call"
id: optional string or null
minLength0
maxLength1048576
namespace: optional string or null
minLength1
maxLength64
status: optional "in_progress" or "completed" or "incomplete" or null
One of the following:
"in_progress"
"completed"
"incomplete"
FunctionCallOutput object { call_id, output, type, 2 more }
call_id: string
minLength1
maxLength64
output: string or array of DecisionInputText { text, type, prompt_cache_breakpoint } or DecisionInputImage { image_url, type, detail, prompt_cache_breakpoint }

Text evidence or an ordered list of text and image parts.

One of the following:
string
Parts = array of DecisionInputText { text, type, prompt_cache_breakpoint } or DecisionInputImage { image_url, type, detail, prompt_cache_breakpoint }
One of the following:
DecisionInputText object { text, type, prompt_cache_breakpoint }
text: string
minLength0
maxLength10485760
type: "input_text"
prompt_cache_breakpoint: optional object { mode } or null

Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request’s prompt_cache_options.ttl; the boundary is not rounded to a token block.

mode: "explicit"

The breakpoint mode. Always explicit.

DecisionInputImage object { image_url, type, detail, prompt_cache_breakpoint }

An image provided as a base64 data URL or a publicly accessible HTTP(S) URL. File IDs are not supported.

image_url: string

A base64-encoded image in a data URL or a publicly accessible HTTP(S) image URL.

minLength0
maxLength1073741824
type: "input_image"
detail: optional "low" or "high" or "auto" or "original" or null

The image detail level, using the selected model’s image profile. Defaults to auto.

One of the following:
"low"
"high"
"auto"
"original"
prompt_cache_breakpoint: optional object { mode } or null

Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request’s prompt_cache_options.ttl; the boundary is not rounded to a token block.

mode: "explicit"

The breakpoint mode. Always explicit.

type: "function_call_output"
id: optional string or null
minLength0
maxLength1048576
status: optional "in_progress" or "completed" or "incomplete" or null
One of the following:
"in_progress"
"completed"
"incomplete"
CustomToolCall object { call_id, input, name, 4 more }
call_id: string
minLength1
maxLength64
input: string
minLength0
maxLength1048576
name: string
minLength1
maxLength64
type: "custom_tool_call"
id: optional string or null
minLength0
maxLength1048576
namespace: optional string or null
minLength1
maxLength64
status: optional "in_progress" or "completed" or "incomplete" or null
One of the following:
"in_progress"
"completed"
"incomplete"
CustomToolCallOutput object { call_id, output, type, 2 more }
call_id: string
minLength1
maxLength64
output: string or array of DecisionInputText { text, type, prompt_cache_breakpoint } or DecisionInputImage { image_url, type, detail, prompt_cache_breakpoint }

Text evidence or an ordered list of text and image parts.

One of the following:
string
Parts = array of DecisionInputText { text, type, prompt_cache_breakpoint } or DecisionInputImage { image_url, type, detail, prompt_cache_breakpoint }
One of the following:
DecisionInputText object { text, type, prompt_cache_breakpoint }
text: string
minLength0
maxLength10485760
type: "input_text"
prompt_cache_breakpoint: optional object { mode } or null

Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request’s prompt_cache_options.ttl; the boundary is not rounded to a token block.

mode: "explicit"

The breakpoint mode. Always explicit.

DecisionInputImage object { image_url, type, detail, prompt_cache_breakpoint }

An image provided as a base64 data URL or a publicly accessible HTTP(S) URL. File IDs are not supported.

image_url: string

A base64-encoded image in a data URL or a publicly accessible HTTP(S) image URL.

minLength0
maxLength1073741824
type: "input_image"
detail: optional "low" or "high" or "auto" or "original" or null

The image detail level, using the selected model’s image profile. Defaults to auto.

One of the following:
"low"
"high"
"auto"
"original"
prompt_cache_breakpoint: optional object { mode } or null

Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request’s prompt_cache_options.ttl; the boundary is not rounded to a token block.

mode: "explicit"

The breakpoint mode. Always explicit.

type: "custom_tool_call_output"
id: optional string or null
minLength0
maxLength1048576
status: optional "in_progress" or "completed" or "incomplete" or null
One of the following:
"in_progress"
"completed"
"incomplete"
model: string

The model to use. Only gpt-6-luna is supported.

minLength0
maxLength1048576
questions: array of Predicate { instructions, type, name } or Choice { choices, instructions, type, name } or Score { instructions, levels, type, name }

Ask 1–400 questions about the input. Each question can be a predicate, choice, or score. Answers come back in the same order.

One of the following:
Predicate object { instructions, type, name }

Estimate how likely it is that a statement about the input is true.

instructions: string or array of DecisionQuestionInputPart
One of the following:
string
array of DecisionQuestionInputPart
One of the following:
DecisionQuestionInputText object { text, type }
text: string
minLength0
maxLength10485760
type: "input_text"
DecisionQuestionInputImage object { image_url, type, detail }

An image provided as a base64 data URL or a publicly accessible HTTP(S) URL. File IDs are not supported.

image_url: string

A base64-encoded image in a data URL or a publicly accessible HTTP(S) image URL.

minLength0
maxLength1073741824
type: "input_image"
detail: optional "low" or "high" or "auto" or "original" or null

The image detail level, using the selected model’s image profile. Defaults to auto.

One of the following:
"low"
"high"
"auto"
"original"
DecisionInputJSON object { data, type }

A JSON object or an array of objects rendered as text. Nested values may be any JSON value. Limited to 32 container levels, 10,000 values, and 256 KiB of compact UTF-8 JSON.

data: map[unknown] or array of map[unknown]
One of the following:
map[unknown]
array of map[unknown]
type: "input_json"
type: "predicate"

The type of the object. Always predicate.

name: optional string
minLength0
maxLength1048576
Choice object { choices, instructions, type, name }

Choose from the supplied options based on the input.

choices: array of object { value, description }

Provide between 2 and 255 choices. Each choice must be unique.

value: string or boolean

Choice values are typed: a string and a boolean with the same text are distinct.

One of the following:
string
boolean
description: optional string
minLength0
maxLength1048576
instructions: string or array of DecisionQuestionInputPart
One of the following:
string
array of DecisionQuestionInputPart
One of the following:
DecisionQuestionInputText object { text, type }
text: string
minLength0
maxLength10485760
type: "input_text"
DecisionQuestionInputImage object { image_url, type, detail }

An image provided as a base64 data URL or a publicly accessible HTTP(S) URL. File IDs are not supported.

image_url: string

A base64-encoded image in a data URL or a publicly accessible HTTP(S) image URL.

minLength0
maxLength1073741824
type: "input_image"
detail: optional "low" or "high" or "auto" or "original" or null

The image detail level, using the selected model’s image profile. Defaults to auto.

One of the following:
"low"
"high"
"auto"
"original"
DecisionInputJSON object { data, type }

A JSON object or an array of objects rendered as text. Nested values may be any JSON value. Limited to 32 container levels, 10,000 values, and 256 KiB of compact UTF-8 JSON.

data: map[unknown] or array of map[unknown]
One of the following:
map[unknown]
array of map[unknown]
type: "input_json"
type: "choice"

The type of the object. Always choice.

name: optional string
minLength0
maxLength1048576
Score object { instructions, levels, type, name }

Rate the input against the supplied ordered levels.

instructions: string or array of DecisionQuestionInputPart
One of the following:
string
array of DecisionQuestionInputPart
One of the following:
DecisionQuestionInputText object { text, type }
text: string
minLength0
maxLength10485760
type: "input_text"
DecisionQuestionInputImage object { image_url, type, detail }

An image provided as a base64 data URL or a publicly accessible HTTP(S) URL. File IDs are not supported.

image_url: string

A base64-encoded image in a data URL or a publicly accessible HTTP(S) image URL.

minLength0
maxLength1073741824
type: "input_image"
detail: optional "low" or "high" or "auto" or "original" or null

The image detail level, using the selected model’s image profile. Defaults to auto.

One of the following:
"low"
"high"
"auto"
"original"
DecisionInputJSON object { data, type }

A JSON object or an array of objects rendered as text. Nested values may be any JSON value. Limited to 32 container levels, 10,000 values, and 256 KiB of compact UTF-8 JSON.

data: map[unknown] or array of map[unknown]
One of the following:
map[unknown]
array of map[unknown]
type: "input_json"
levels: array of object { label, description }
label: string
minLength0
maxLength1048576
description: optional string
minLength0
maxLength1048576
type: "score"

The type of the object. Always score.

name: optional string
minLength0
maxLength1048576
prompt_cache_key: optional string or null

Partition prompt cache reuse by caller-provided key.

minLength0
maxLength64
prompt_cache_options: optional object { mode, ttl } or null

Options for prompt caching. Supported for gpt-5.6 and later models. By default, OpenAI automatically chooses one implicit cache breakpoint. You can add explicit breakpoints to content blocks with prompt_cache_breakpoint. Each request can write up to four breakpoints. For cache matching, OpenAI considers up to the latest 80 breakpoints in the conversation, without a content-block lookback limit. Set mode to explicit to disable the implicit breakpoint. The ttl defaults to 30m, which is currently the only supported value. See the prompt caching guide for current details.

mode: optional "implicit" or "explicit" or null

Controls whether OpenAI automatically creates an implicit cache breakpoint. Defaults to implicit. With implicit, OpenAI creates one implicit breakpoint and writes up to the latest three explicit breakpoints in the request. With explicit, OpenAI does not create an implicit breakpoint and writes up to the latest four explicit breakpoints. If there are no explicit breakpoints, the request does not use prompt caching.

One of the following:
"implicit"
"explicit"
ttl: optional "30m"

The minimum lifetime applied to every implicit and explicit cache breakpoint written by the request. Defaults to 30m, which is currently the only supported value. The backend may retain cache entries for longer.

safety_identifier: optional string or null

Opaque caller-provided end-user identifier, scoped by the verified org. Match Responses’ limit; this is never the authenticated user identity.

minLength0
maxLength128
Returns
Decision object { answers, model, usage }
answers: array of Predicate { name, probability, type } or Choice { choice, confidence, name, 2 more } or Score { confidence, name, probabilities, 2 more } or Refusal { name, type }

Answers in question order. Any question can return a refusal instead of an answer; other questions can still receive answers. A refusal has type: "refusal" and the question’s name, or null if it was unnamed.

One of the following:
Predicate object { name, probability, type }
name: string or null
minLength0
probability: number
type: "predicate"

The type of the object. Always predicate.

Choice object { choice, confidence, name, 2 more }
choice: string or boolean

Choice values are typed: a string and a boolean with the same text are distinct.

One of the following:
string
boolean
confidence: number
name: string or null
minLength0
probabilities: array of object { probability, value }
probability: number
value: string or boolean

Choice values are typed: a string and a boolean with the same text are distinct.

One of the following:
string
boolean
type: "choice"

The type of the object. Always choice.

Score object { confidence, name, probabilities, 2 more }
confidence: number
name: string or null
minLength0
probabilities: array of object { label, probability, value }
label: string
minLength0
probability: number
value: number
formatint64
score: number
type: "score"

The type of the object. Always score.

Refusal object { name, type }

The model declined to answer this question. Other questions in the same request can still receive answers.

name: string or null
minLength0
type: "refusal"

The type of the object. Always refusal.

model: string

The model used.

minLength0
usage: object { input_tokens, input_tokens_details, output_tokens, 2 more }

Token usage for the request.

input_tokens: number
formatint64
minimum-2147483648
maximum2147483647
input_tokens_details: object { cache_write_tokens, cached_tokens }
cache_write_tokens: number
formatint64
minimum-2147483648
maximum2147483647
cached_tokens: number
formatint64
minimum-2147483648
maximum2147483647
output_tokens: number
formatint64
minimum-2147483648
maximum2147483647
output_tokens_details: object { reasoning_tokens }
reasoning_tokens: number
formatint64
minimum-2147483648
maximum2147483647
total_tokens: number
formatint64
minimum-2147483648
maximum2147483647

Create a decision

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

{
  "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
  }
}
Returns Examples
{
  "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
  }
}