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
Theme

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.

minItems0
maxItems2000
One of the following:
Predicate object { name, probability, type }
name: string or null
minLength0
probability: number
type: "predicate" (default: "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
minLength0
boolean
confidence: number
name: string or null
minLength0
probabilities: array of object { probability, value }
minItems0
maxItems2000
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
minLength0
boolean
type: "choice" (default: "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 }
minItems0
maxItems2000
label: string
minLength0
probability: number
value: integer
formatint64
score: number
type: "score" (default: "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" (default: "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: integer
formatint64
minimum-2147483648
maximum2147483647
input_tokens_details: object { cache_write_tokens, cached_tokens }
cache_write_tokens: integer
formatint64
minimum-2147483648
maximum2147483647
cached_tokens: integer
formatint64
minimum-2147483648
maximum2147483647
output_tokens: integer
formatint64
minimum-2147483648
maximum2147483647
output_tokens_details: object { reasoning_tokens }
reasoning_tokens: integer
formatint64
minimum-2147483648
maximum2147483647
total_tokens: integer
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.

pattern^(data:|https?://)
minLength0
maxLength1073741824
type: "input_image" (default: "input_image")
detail: optional "low" or "high" or "auto" or "original" or null (default: "auto")

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" (default: "explicit")

The breakpoint mode. Always explicit.

DecisionInputMessage = User { content, role, type } or Developer { content, role, type } or System { content, role, type } or Assistant { content, role, phase, type }

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

One of the following:
User 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
minLength0
maxLength10485760
Parts = array of DecisionInputPart
minItems0
maxItems16384
One of the following:
DecisionInputText object { text, type, prompt_cache_breakpoint }
text: string
minLength0
maxLength10485760
type: "input_text" (default: "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" (default: "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.

pattern^(data:|https?://)
minLength0
maxLength1073741824
type: "input_image" (default: "input_image")
detail: optional "low" or "high" or "auto" or "original" or null (default: "auto")

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" (default: "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]
minItems0
type: "input_json" (default: "input_json")
role: "user" (default: "user")
type: optional "message" (default: "message")
Developer 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
minLength0
maxLength10485760
Parts = array of DecisionInputText { text, type, prompt_cache_breakpoint }
minItems0
maxItems16384
text: string
minLength0
maxLength10485760
type: "input_text" (default: "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" (default: "explicit")

The breakpoint mode. Always explicit.

role: "developer" (default: "developer")
type: optional "message" (default: "message")
System 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
minLength0
maxLength10485760
Parts = array of DecisionInputText { text, type, prompt_cache_breakpoint }
minItems0
maxItems16384
text: string
minLength0
maxLength10485760
type: "input_text" (default: "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" (default: "explicit")

The breakpoint mode. Always explicit.

role: "system" (default: "system")
type: optional "message" (default: "message")
Assistant 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
minLength0
maxLength10485760
Parts = array of OutputText { text, type } or Refusal { refusal, type }
minItems0
maxItems16384
One of the following:
OutputText object { text, type }
text: string
minLength0
maxLength10485760
type: "output_text" (default: "output_text")
Refusal object { refusal, type }
refusal: string
minLength0
maxLength10485760
type: "refusal" (default: "refusal")
role: "assistant" (default: "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" (default: "message")
DecisionInputPart = DecisionInputText { text, type, prompt_cache_breakpoint } or DecisionInputImage { image_url, type, detail, prompt_cache_breakpoint } or DecisionInputJSON { data, 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" (default: "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" (default: "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.

pattern^(data:|https?://)
minLength0
maxLength1073741824
type: "input_image" (default: "input_image")
detail: optional "low" or "high" or "auto" or "original" or null (default: "auto")

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" (default: "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]
minItems0
type: "input_json" (default: "input_json")
DecisionInputText object { text, type, prompt_cache_breakpoint }
text: string
minLength0
maxLength10485760
type: "input_text" (default: "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" (default: "explicit")

The breakpoint mode. Always explicit.