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

Decisions

Create a decision
POST
/decisions
Models
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
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.

DecisionInputMessage object { content, role, phase, type }

A user message containing input text or images, a developer or system message containing input text, or an assistant message containing output text or refusals. System messages are rendered as developer messages.

content: string or array of DecisionInputPart

Text evidence or an ordered list of text and image 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.

OutputText object { text, type }
text: string
minLength0
maxLength10485760
type: "output_text"
Refusal object { refusal, type }
refusal: string
minLength0
maxLength10485760
type: "refusal"
role: "user" or "developer" or "system" or "assistant"
One of the following:
"user"
"developer"
"system"
"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"
DecisionInputPart = DecisionInputText { text, type, prompt_cache_breakpoint } or DecisionInputImage { image_url, type, detail, prompt_cache_breakpoint } or OutputText { text, type } or Refusal { refusal, type }

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

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.

OutputText object { text, type }
text: string
minLength0
maxLength10485760
type: "output_text"
Refusal object { refusal, type }
refusal: string
minLength0
maxLength10485760
type: "refusal"
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.