diff --git a/en/ruby/resources/responses/index.md b/en/ruby/resources/responses/index.md index 6065942..9ecd15c 100644 --- a/en/ruby/resources/responses/index.md +++ b/en/ruby/resources/responses/index.md @@ -6,13 +6,7 @@ **post** `/responses` -Creates a model response. Provide [text](https://platform.openai.com/docs/guides/text) or -[image](https://platform.openai.com/docs/guides/images) inputs to generate [text](https://platform.openai.com/docs/guides/text) -or [JSON](https://platform.openai.com/docs/guides/structured-outputs) outputs. Have the model call -your own [custom code](https://platform.openai.com/docs/guides/function-calling) or use built-in -[tools](https://platform.openai.com/docs/guides/tools) like [web search](https://platform.openai.com/docs/guides/tools-web-search) -or [file search](https://platform.openai.com/docs/guides/tools-file-search) to use your own data -as input for the model's response. +Create a model response ### Parameters @@ -136,6 +130,16 @@ as input for the model's response. - `:input_text` + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + + 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`. + + - `:explicit` + - `class ResponseInputImage` An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). @@ -166,6 +170,16 @@ as input for the model's response. The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + + 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`. + + - `:explicit` + - `class ResponseInputFile` A file input to the model. @@ -176,9 +190,11 @@ as input for the model's response. - `:input_file` - - `detail: :low | :high` + - `detail: :auto | :low | :high` + + The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. - The detail level of the file to be sent to the model. Use `low` for the default rendering behavior, or `high` to render the file at higher quality. Defaults to `low`. + - `:auto` - `:low` @@ -200,6 +216,16 @@ as input for the model's response. The name of the file to be sent to the model. + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + + 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`. + + - `:explicit` + - `role: :user | :assistant | :system | :developer` The role of the message input. One of `user`, `assistant`, `system`, or @@ -1147,6 +1173,26 @@ as input for the model's response. The unique ID of the function tool call. + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + - `:program` + - `namespace: String` The namespace of the function to run. @@ -1196,6 +1242,16 @@ as input for the model's response. - `:input_text` + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + + 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`. + + - `:explicit` + - `class ResponseInputImageContent` An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) @@ -1226,6 +1282,16 @@ as input for the model's response. The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + + 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`. + + - `:explicit` + - `class ResponseInputFileContent` A file input to the model. @@ -1236,9 +1302,11 @@ as input for the model's response. - `:input_file` - - `detail: :low | :high` + - `detail: :auto | :low | :high` - The detail level of the file to be sent to the model. Use `low` for the default rendering behavior, or `high` to render the file at higher quality. Defaults to `low`. + The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. + + - `:auto` - `:low` @@ -1260,6 +1328,16 @@ as input for the model's response. The name of the file to be sent to the model. + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + + 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`. + + - `:explicit` + - `type: :function_call_output` The type of the function tool call output. Always `function_call_output`. @@ -1270,6 +1348,30 @@ as input for the model's response. The unique ID of the function tool call output. Populated when this item is returned via API. + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + The caller type. Always `direct`. + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + The caller type. Always `program`. + + - `:program` + - `status: :in_progress | :completed | :incomplete` The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. @@ -1338,7 +1440,7 @@ as input for the model's response. - `strict: bool` - Whether to enforce strict parameter validation. Default `true`. + Whether strict parameter validation is enforced for this function tool. - `type: :function` @@ -1346,6 +1448,14 @@ as input for the model's response. - `:function` + - `allowed_callers: Array[:direct | :programmatic]` + + The tool invocation context(s). + + - `:direct` + + - `:programmatic` + - `defer_loading: bool` Whether this function is deferred and loaded via tool search. @@ -1354,6 +1464,10 @@ as input for the model's response. A description of the function. Used by the model to determine whether or not to call the function. + - `output_schema: Hash[Symbol, untyped]` + + A JSON schema object describing the JSON value encoded in string outputs for this function. + - `class FileSearchTool` A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). @@ -1409,7 +1523,7 @@ as input for the model's response. - `:nin` - - `value: String | Float | bool | Array[String | Float]` + - `value: String | Float | bool | Array[untyped]` The value to compare against the attribute key; supports string, number, or boolean types. @@ -1419,11 +1533,7 @@ as input for the model's response. - `UnionMember2 = bool` - - `UnionMember3 = Array[String | Float]` - - - `String = String` - - - `Float = Float` + - `UnionMember3 = Array[untyped]` - `class CompoundFilter` @@ -1596,6 +1706,14 @@ as input for the model's response. - `:mcp` + - `allowed_callers: Array[:direct | :programmatic]` + + The tool invocation context(s). + + - `:direct` + + - `:programmatic` + - `allowed_tools: Array[String] | McpToolFilter{ read_only, tool_names}` List of allowed tool names or a filter object. @@ -1814,6 +1932,22 @@ as input for the model's response. - `:code_interpreter` + - `allowed_callers: Array[:direct | :programmatic]` + + The tool invocation context(s). + + - `:direct` + + - `:programmatic` + + - `class ProgrammaticToolCalling` + + - `type: :programmatic_tool_calling` + + The type of the tool. Always `programmatic_tool_calling`. + + - `:programmatic_tool_calling` + - `class ImageGeneration` A tool that generates images using the GPT image models. @@ -1977,6 +2111,14 @@ as input for the model's response. - `:shell` + - `allowed_callers: Array[:direct | :programmatic]` + + The tool invocation context(s). + + - `:direct` + + - `:programmatic` + - `environment: ContainerAuto | LocalEnvironment | ContainerReference` - `class ContainerAuto` @@ -2117,6 +2259,14 @@ as input for the model's response. - `:custom` + - `allowed_callers: Array[:direct | :programmatic]` + + The tool invocation context(s). + + - `:direct` + + - `:programmatic` + - `defer_loading: bool` Whether this tool should be deferred and discovered via tool search. @@ -2173,7 +2323,7 @@ as input for the model's response. The namespace name used in tool calls (for example, `crm`). - - `tools: Array[Function{ name, type, defer_loading, 3 more} | CustomTool]` + - `tools: Array[Function{ name, type, allowed_callers, 5 more} | CustomTool]` The function/custom tools available inside this namespace. @@ -2185,16 +2335,30 @@ as input for the model's response. - `:function` + - `allowed_callers: Array[:direct | :programmatic]` + + The tool invocation context(s). + + - `:direct` + + - `:programmatic` + - `defer_loading: bool` Whether this function should be deferred and discovered via tool search. - `description: String` + - `output_schema: Hash[Symbol, untyped]` + + A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. + - `parameters: untyped` - `strict: bool` + Whether to enforce strict parameter validation. If omitted, Responses attempts to use strict validation when the schema is compatible, and falls back to non-strict validation otherwise. + - `class CustomTool` A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) @@ -2295,6 +2459,14 @@ as input for the model's response. - `:apply_patch` + - `allowed_callers: Array[:direct | :programmatic]` + + The tool invocation context(s). + + - `:direct` + + - `:programmatic` + - `type: :tool_search_output` The item type. Always `tool_search_output`. @@ -2369,6 +2541,8 @@ as input for the model's response. A tool that runs Python code to help generate a response to a prompt. + - `class ProgrammaticToolCalling` + - `class ImageGeneration` A tool that generates images using the GPT image models. @@ -2709,6 +2883,30 @@ as input for the model's response. The unique ID of the shell tool call. Populated when this item is returned via API. + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + The caller type. Always `direct`. + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + The caller type. Always `program`. + + - `:program` + - `environment: LocalEnvironment | ContainerReference` The environment to execute the shell commands in. @@ -2785,6 +2983,30 @@ as input for the model's response. The unique ID of the shell tool call output. Populated when this item is returned via API. + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + The caller type. Always `direct`. + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + The caller type. Always `program`. + + - `:program` + - `max_output_length: Integer` The maximum number of UTF-8 characters captured for this shell call's combined output. @@ -2879,6 +3101,30 @@ as input for the model's response. The unique ID of the apply patch tool call. Populated when this item is returned via API. + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + The caller type. Always `direct`. + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + The caller type. Always `program`. + + - `:program` + - `class ApplyPatchCallOutput` The streamed output emitted by an apply patch tool call. @@ -2905,6 +3151,30 @@ as input for the model's response. The unique ID of the apply patch tool call output. Populated when this item is returned via API. + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + The caller type. Always `direct`. + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + The caller type. Always `program`. + + - `:program` + - `output: String` Optional human-readable log text from the apply patch tool (e.g., patch results or errors). @@ -3099,6 +3369,30 @@ as input for the model's response. The unique ID of the custom tool call output in the OpenAI platform. + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + The caller type. Always `direct`. + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + The caller type. Always `program`. + + - `:program` + - `class ResponseCustomToolCall` A call to a custom tool created by the model. @@ -3125,6 +3419,26 @@ as input for the model's response. The unique ID of the custom tool call in the OpenAI platform. + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + - `:program` + - `namespace: String` The namespace of the custom tool being called. @@ -3153,6 +3467,58 @@ as input for the model's response. - `:item_reference` + - `class Program` + + - `id: String` + + The unique ID of this program item. + + - `call_id: String` + + The stable call ID of the program item. + + - `code: String` + + The JavaScript source executed by programmatic tool calling. + + - `fingerprint: String` + + Opaque program replay fingerprint that must be round-tripped. + + - `type: :program` + + The item type. Always `program`. + + - `:program` + + - `class ProgramOutput` + + - `id: String` + + The unique ID of this program output item. + + - `call_id: String` + + The call ID of the program item. + + - `result: String` + + The result produced by the program item. + + - `status: :completed | :incomplete` + + The terminal status of the program output. + + - `:completed` + + - `:incomplete` + + - `type: :program_output` + + The item type. Always `program_output`. + + - `:program_output` + - `instructions: String` A system (or developer) message inserted into the model's context. @@ -3187,7 +3553,13 @@ as input for the model's response. - `String = String` - - `ChatModel = :"gpt-5.4" | :"gpt-5.4-mini" | :"gpt-5.4-nano" | 75 more` + - `ChatModel = :"gpt-5.6-sol" | :"gpt-5.6-terra" | :"gpt-5.6-luna" | 78 more` + + - `:"gpt-5.6-sol"` + + - `:"gpt-5.6-terra"` + + - `:"gpt-5.6-luna"` - `:"gpt-5.4"` @@ -3375,7 +3747,7 @@ as input for the model's response. - `:"gpt-5.1-codex-max"` -- `moderation: Moderation{ model}` +- `moderation: Moderation{ model, policy}` Configuration for running moderation on the input and output of this response. @@ -3383,6 +3755,30 @@ as input for the model's response. The moderation model to use for moderated completions, e.g. 'omni-moderation-latest'. + - `policy: Policy{ input, output}` + + The policy to apply to moderated response input and output. + + - `input: Input{ mode}` + + The moderation policy for the response input. + + - `mode: :score | :block` + + - `:score` + + - `:block` + + - `output: Output{ mode}` + + The moderation policy for the response output. + + - `mode: :score | :block` + + - `:score` + + - `:block` + - `parallel_tool_calls: bool` Whether to allow the model to run tool calls in parallel. @@ -3430,9 +3826,32 @@ as input for the model's response. Used by OpenAI to cache responses for similar requests to optimize your cache hit rates. Replaces the `user` field. [Learn more](https://platform.openai.com/docs/guides/prompt-caching). +- `prompt_cache_options: PromptCacheOptions{ mode, ttl}` + + 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](https://platform.openai.com/docs/guides/prompt-caching) for current details. + + - `mode: :implicit | :explicit` + + 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. + + - `:implicit` + + - `:explicit` + + - `ttl: :"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. + + - `:"30m"` + - `prompt_cache_retention: :in_memory | :"24h"` + Deprecated. Use `prompt_cache_options.ttl` instead. + The retention policy for the prompt cache. Set to `24h` to enable extended prompt caching, which keeps cached prefixes active for longer, up to a maximum of 24 hours. [Learn more](https://platform.openai.com/docs/guides/prompt-caching#prompt-cache-retention). + This field expresses a maximum retention policy, while + `prompt_cache_options.ttl` expresses a minimum cache lifetime. The two + fields are independent and do not interact. For `gpt-5.5`, `gpt-5.5-pro`, and future models, only `24h` is supported. For older models that support both `in_memory` and `24h`, the default depends on your organization's data retention policy: @@ -3465,16 +3884,13 @@ as input for the model's response. - `effort: ReasoningEffort` - Constrains effort on reasoning for - [reasoning models](https://platform.openai.com/docs/guides/reasoning). - Currently supported values are `none`, `minimal`, `low`, `medium`, `high`, and `xhigh`. Reducing - reasoning effort can result in faster responses and fewer tokens used - on reasoning in a response. - - - `gpt-5.1` defaults to `none`, which does not perform reasoning. The supported reasoning values for `gpt-5.1` are `none`, `low`, `medium`, and `high`. Tool calls are supported for all reasoning values in gpt-5.1. - - All models before `gpt-5.1` default to `medium` reasoning effort, and do not support `none`. - - The `gpt-5-pro` model defaults to (and only supports) `high` reasoning effort. - - `xhigh` is supported for all models after `gpt-5.1-codex-max`. + Constrains effort on reasoning for reasoning models. Currently supported + values are `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max`. + Reducing reasoning effort can result in faster responses and fewer tokens + used on reasoning in a response. Not all reasoning models support every + value. See the + [reasoning guide](https://platform.openai.com/docs/guides/reasoning) + for model-specific support. - `:none` @@ -3488,6 +3904,8 @@ as input for the model's response. - `:xhigh` + - `:max` + - `generate_summary: :auto | :concise | :detailed` **Deprecated:** use `summary` instead. @@ -3502,6 +3920,24 @@ as input for the model's response. - `:detailed` + - `mode: String | :standard | :pro` + + Controls the reasoning execution mode for the request. + + When returned on a response, this is the effective execution mode. + + - `String = String` + + - `Mode = :standard | :pro` + + Controls the reasoning execution mode for the request. + + When returned on a response, this is the effective execution mode. + + - `:standard` + + - `:pro` + - `summary: :auto | :concise | :detailed` A summary of the reasoning performed by the model. This can be @@ -3666,7 +4102,7 @@ as input for the model's response. - `:high` -- `tool_choice: ToolChoiceOptions | ToolChoiceAllowed | ToolChoiceTypes | 5 more` +- `tool_choice: ToolChoiceOptions | ToolChoiceAllowed | ToolChoiceTypes | 6 more` How the model should select which tool (or tools) to use when generating a response. See the `tools` parameter to see how to specify which tools @@ -3808,6 +4244,14 @@ as input for the model's response. - `:custom` + - `class SpecificProgrammaticToolCallingParam` + + - `type: :programmatic_tool_calling` + + The tool to call. Always `programmatic_tool_calling`. + + - `:programmatic_tool_calling` + - `class ToolChoiceApplyPatch` Forces the model to call the apply_patch tool when executing a tool call. @@ -3878,6 +4322,8 @@ as input for the model's response. A tool that runs Python code to help generate a response to a prompt. + - `class ProgrammaticToolCalling` + - `class ImageGeneration` A tool that generates images using the GPT image models. @@ -3962,7 +4408,7 @@ as input for the model's response. An error object returned when the model fails to generate a Response. - - `code: :server_error | :rate_limit_exceeded | :invalid_prompt | 15 more` + - `code: :server_error | :rate_limit_exceeded | :invalid_prompt | 16 more` The error code for the response. @@ -3972,6 +4418,8 @@ as input for the model's response. - `:invalid_prompt` + - `:bio_policy` + - `:vector_store_timeout` - `:invalid_image` @@ -4072,6 +4520,16 @@ as input for the model's response. - `:input_text` + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + + 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`. + + - `:explicit` + - `class ResponseInputImage` An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). @@ -4102,6 +4560,16 @@ as input for the model's response. The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + + 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`. + + - `:explicit` + - `class ResponseInputFile` A file input to the model. @@ -4112,9 +4580,11 @@ as input for the model's response. - `:input_file` - - `detail: :low | :high` + - `detail: :auto | :low | :high` - The detail level of the file to be sent to the model. Use `low` for the default rendering behavior, or `high` to render the file at higher quality. Defaults to `low`. + The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. + + - `:auto` - `:low` @@ -4136,6 +4606,16 @@ as input for the model's response. The name of the file to be sent to the model. + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + + 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`. + + - `:explicit` + - `role: :user | :assistant | :system | :developer` The role of the message input. One of `user`, `assistant`, `system`, or @@ -5083,6 +5563,26 @@ as input for the model's response. The unique ID of the function tool call. + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + - `:program` + - `namespace: String` The namespace of the function to run. @@ -5132,6 +5632,16 @@ as input for the model's response. - `:input_text` + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + + 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`. + + - `:explicit` + - `class ResponseInputImageContent` An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) @@ -5162,6 +5672,16 @@ as input for the model's response. The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + + 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`. + + - `:explicit` + - `class ResponseInputFileContent` A file input to the model. @@ -5172,9 +5692,11 @@ as input for the model's response. - `:input_file` - - `detail: :low | :high` + - `detail: :auto | :low | :high` - The detail level of the file to be sent to the model. Use `low` for the default rendering behavior, or `high` to render the file at higher quality. Defaults to `low`. + The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. + + - `:auto` - `:low` @@ -5196,6 +5718,16 @@ as input for the model's response. The name of the file to be sent to the model. + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + + 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`. + + - `:explicit` + - `type: :function_call_output` The type of the function tool call output. Always `function_call_output`. @@ -5206,6 +5738,30 @@ as input for the model's response. The unique ID of the function tool call output. Populated when this item is returned via API. + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + The caller type. Always `direct`. + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + The caller type. Always `program`. + + - `:program` + - `status: :in_progress | :completed | :incomplete` The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. @@ -5274,7 +5830,7 @@ as input for the model's response. - `strict: bool` - Whether to enforce strict parameter validation. Default `true`. + Whether strict parameter validation is enforced for this function tool. - `type: :function` @@ -5282,6 +5838,14 @@ as input for the model's response. - `:function` + - `allowed_callers: Array[:direct | :programmatic]` + + The tool invocation context(s). + + - `:direct` + + - `:programmatic` + - `defer_loading: bool` Whether this function is deferred and loaded via tool search. @@ -5290,6 +5854,10 @@ as input for the model's response. A description of the function. Used by the model to determine whether or not to call the function. + - `output_schema: Hash[Symbol, untyped]` + + A JSON schema object describing the JSON value encoded in string outputs for this function. + - `class FileSearchTool` A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). @@ -5345,7 +5913,7 @@ as input for the model's response. - `:nin` - - `value: String | Float | bool | Array[String | Float]` + - `value: String | Float | bool | Array[untyped]` The value to compare against the attribute key; supports string, number, or boolean types. @@ -5355,11 +5923,7 @@ as input for the model's response. - `UnionMember2 = bool` - - `UnionMember3 = Array[String | Float]` - - - `String = String` - - - `Float = Float` + - `UnionMember3 = Array[untyped]` - `class CompoundFilter` @@ -5532,6 +6096,14 @@ as input for the model's response. - `:mcp` + - `allowed_callers: Array[:direct | :programmatic]` + + The tool invocation context(s). + + - `:direct` + + - `:programmatic` + - `allowed_tools: Array[String] | McpToolFilter{ read_only, tool_names}` List of allowed tool names or a filter object. @@ -5750,6 +6322,22 @@ as input for the model's response. - `:code_interpreter` + - `allowed_callers: Array[:direct | :programmatic]` + + The tool invocation context(s). + + - `:direct` + + - `:programmatic` + + - `class ProgrammaticToolCalling` + + - `type: :programmatic_tool_calling` + + The type of the tool. Always `programmatic_tool_calling`. + + - `:programmatic_tool_calling` + - `class ImageGeneration` A tool that generates images using the GPT image models. @@ -5913,6 +6501,14 @@ as input for the model's response. - `:shell` + - `allowed_callers: Array[:direct | :programmatic]` + + The tool invocation context(s). + + - `:direct` + + - `:programmatic` + - `environment: ContainerAuto | LocalEnvironment | ContainerReference` - `class ContainerAuto` @@ -6053,6 +6649,14 @@ as input for the model's response. - `:custom` + - `allowed_callers: Array[:direct | :programmatic]` + + The tool invocation context(s). + + - `:direct` + + - `:programmatic` + - `defer_loading: bool` Whether this tool should be deferred and discovered via tool search. @@ -6109,7 +6713,7 @@ as input for the model's response. The namespace name used in tool calls (for example, `crm`). - - `tools: Array[Function{ name, type, defer_loading, 3 more} | CustomTool]` + - `tools: Array[Function{ name, type, allowed_callers, 5 more} | CustomTool]` The function/custom tools available inside this namespace. @@ -6121,16 +6725,30 @@ as input for the model's response. - `:function` + - `allowed_callers: Array[:direct | :programmatic]` + + The tool invocation context(s). + + - `:direct` + + - `:programmatic` + - `defer_loading: bool` Whether this function should be deferred and discovered via tool search. - `description: String` + - `output_schema: Hash[Symbol, untyped]` + + A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. + - `parameters: untyped` - `strict: bool` + Whether to enforce strict parameter validation. If omitted, Responses attempts to use strict validation when the schema is compatible, and falls back to non-strict validation otherwise. + - `class CustomTool` A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) @@ -6231,6 +6849,14 @@ as input for the model's response. - `:apply_patch` + - `allowed_callers: Array[:direct | :programmatic]` + + The tool invocation context(s). + + - `:direct` + + - `:programmatic` + - `type: :tool_search_output` The item type. Always `tool_search_output`. @@ -6305,6 +6931,8 @@ as input for the model's response. A tool that runs Python code to help generate a response to a prompt. + - `class ProgrammaticToolCalling` + - `class ImageGeneration` A tool that generates images using the GPT image models. @@ -6645,6 +7273,30 @@ as input for the model's response. The unique ID of the shell tool call. Populated when this item is returned via API. + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + The caller type. Always `direct`. + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + The caller type. Always `program`. + + - `:program` + - `environment: LocalEnvironment | ContainerReference` The environment to execute the shell commands in. @@ -6721,6 +7373,30 @@ as input for the model's response. The unique ID of the shell tool call output. Populated when this item is returned via API. + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + The caller type. Always `direct`. + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + The caller type. Always `program`. + + - `:program` + - `max_output_length: Integer` The maximum number of UTF-8 characters captured for this shell call's combined output. @@ -6815,6 +7491,30 @@ as input for the model's response. The unique ID of the apply patch tool call. Populated when this item is returned via API. + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + The caller type. Always `direct`. + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + The caller type. Always `program`. + + - `:program` + - `class ApplyPatchCallOutput` The streamed output emitted by an apply patch tool call. @@ -6841,6 +7541,30 @@ as input for the model's response. The unique ID of the apply patch tool call output. Populated when this item is returned via API. + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + The caller type. Always `direct`. + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + The caller type. Always `program`. + + - `:program` + - `output: String` Optional human-readable log text from the apply patch tool (e.g., patch results or errors). @@ -7035,6 +7759,30 @@ as input for the model's response. The unique ID of the custom tool call output in the OpenAI platform. + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + The caller type. Always `direct`. + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + The caller type. Always `program`. + + - `:program` + - `class ResponseCustomToolCall` A call to a custom tool created by the model. @@ -7061,6 +7809,26 @@ as input for the model's response. The unique ID of the custom tool call in the OpenAI platform. + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + - `:program` + - `namespace: String` The namespace of the custom tool being called. @@ -7089,6 +7857,58 @@ as input for the model's response. - `:item_reference` + - `class Program` + + - `id: String` + + The unique ID of this program item. + + - `call_id: String` + + The stable call ID of the program item. + + - `code: String` + + The JavaScript source executed by programmatic tool calling. + + - `fingerprint: String` + + Opaque program replay fingerprint that must be round-tripped. + + - `type: :program` + + The item type. Always `program`. + + - `:program` + + - `class ProgramOutput` + + - `id: String` + + The unique ID of this program output item. + + - `call_id: String` + + The call ID of the program item. + + - `result: String` + + The result produced by the program item. + + - `status: :completed | :incomplete` + + The terminal status of the program output. + + - `:completed` + + - `:incomplete` + + - `type: :program_output` + + The item type. Always `program_output`. + + - `:program_output` + - `metadata: Metadata` Set of 16 key-value pairs that can be attached to an object. This can be @@ -7107,7 +7927,13 @@ as input for the model's response. - `String = String` - - `ChatModel = :"gpt-5.4" | :"gpt-5.4-mini" | :"gpt-5.4-nano" | 75 more` + - `ChatModel = :"gpt-5.6-sol" | :"gpt-5.6-terra" | :"gpt-5.6-luna" | 78 more` + + - `:"gpt-5.6-sol"` + + - `:"gpt-5.6-terra"` + + - `:"gpt-5.6-luna"` - `:"gpt-5.4"` @@ -7378,6 +8204,30 @@ as input for the model's response. - `:function_call_output` + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + The caller type. Always `direct`. + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + The caller type. Always `program`. + + - `:program` + - `created_by: String` The identifier of the actor that created the item. @@ -7453,6 +8303,58 @@ as input for the model's response. for subsequent turns of a conversation if you are manually [managing context](https://platform.openai.com/docs/guides/conversation-state). + - `class Program` + + - `id: String` + + The unique ID of the program item. + + - `call_id: String` + + The stable call ID of the program item. + + - `code: String` + + The JavaScript source executed by programmatic tool calling. + + - `fingerprint: String` + + Opaque program replay fingerprint that must be round-tripped. + + - `type: :program` + + The type of the item. Always `program`. + + - `:program` + + - `class ProgramOutput` + + - `id: String` + + The unique ID of the program output item. + + - `call_id: String` + + The call ID of the program item. + + - `result: String` + + The result produced by the program item. + + - `status: :completed | :incomplete` + + The terminal status of the program output item. + + - `:completed` + + - `:incomplete` + + - `type: :program_output` + + The type of the item. Always `program_output`. + + - `:program_output` + - `class ResponseToolSearchCall` - `id: String` @@ -7557,6 +8459,8 @@ as input for the model's response. A tool that runs Python code to help generate a response to a prompt. + - `class ProgrammaticToolCalling` + - `class ImageGeneration` A tool that generates images using the GPT image models. @@ -7659,6 +8563,8 @@ as input for the model's response. A tool that runs Python code to help generate a response to a prompt. + - `class ProgrammaticToolCalling` + - `class ImageGeneration` A tool that generates images using the GPT image models. @@ -7907,6 +8813,26 @@ as input for the model's response. - `:shell_call` + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + - `:program` + - `created_by: String` The ID of the entity that created this tool call. @@ -7987,6 +8913,26 @@ as input for the model's response. - `:shell_call_output` + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + - `:program` + - `created_by: String` The identifier of the actor that created the item. @@ -8071,6 +9017,26 @@ as input for the model's response. - `:apply_patch_call` + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + - `:program` + - `created_by: String` The ID of the entity that created this tool call. @@ -8101,6 +9067,26 @@ as input for the model's response. - `:apply_patch_call_output` + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + - `:program` + - `created_by: String` The ID of the entity that created this tool call output. @@ -8292,7 +9278,7 @@ as input for the model's response. What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. We generally recommend altering this or `top_p` but not both. - - `tool_choice: ToolChoiceOptions | ToolChoiceAllowed | ToolChoiceTypes | 5 more` + - `tool_choice: ToolChoiceOptions | ToolChoiceAllowed | ToolChoiceTypes | 6 more` How the model should select which tool (or tools) to use when generating a response. See the `tools` parameter to see how to specify which tools @@ -8434,6 +9420,14 @@ as input for the model's response. - `:custom` + - `class SpecificProgrammaticToolCallingParam` + + - `type: :programmatic_tool_calling` + + The tool to call. Always `programmatic_tool_calling`. + + - `:programmatic_tool_calling` + - `class ToolChoiceApplyPatch` Forces the model to call the apply_patch tool when executing a tool call. @@ -8504,6 +9498,8 @@ as input for the model's response. A tool that runs Python code to help generate a response to a prompt. + - `class ProgrammaticToolCalling` + - `class ImageGeneration` A tool that generates images using the GPT image models. @@ -8730,9 +9726,32 @@ as input for the model's response. Used by OpenAI to cache responses for similar requests to optimize your cache hit rates. Replaces the `user` field. [Learn more](https://platform.openai.com/docs/guides/prompt-caching). + - `prompt_cache_options: PromptCacheOptions{ mode, ttl}` + + The prompt-caching options that were applied to the response. Supported for `gpt-5.6` and later models. + + - `mode: :implicit | :explicit` + + Whether implicit prompt-cache breakpoints were enabled. + + - `:implicit` + + - `:explicit` + + - `ttl: :"30m"` + + The minimum lifetime applied to each cache breakpoint. + + - `:"30m"` + - `prompt_cache_retention: :in_memory | :"24h"` + Deprecated. Use `prompt_cache_options.ttl` instead. + The retention policy for the prompt cache. Set to `24h` to enable extended prompt caching, which keeps cached prefixes active for longer, up to a maximum of 24 hours. [Learn more](https://platform.openai.com/docs/guides/prompt-caching#prompt-cache-retention). + This field expresses a maximum retention policy, while + `prompt_cache_options.ttl` expresses a minimum cache lifetime. The two + fields are independent and do not interact. For `gpt-5.5`, `gpt-5.5-pro`, and future models, only `24h` is supported. For older models that support both `in_memory` and `24h`, the default depends on your organization's data retention policy: @@ -8765,16 +9784,13 @@ as input for the model's response. - `effort: ReasoningEffort` - Constrains effort on reasoning for - [reasoning models](https://platform.openai.com/docs/guides/reasoning). - Currently supported values are `none`, `minimal`, `low`, `medium`, `high`, and `xhigh`. Reducing - reasoning effort can result in faster responses and fewer tokens used - on reasoning in a response. - - - `gpt-5.1` defaults to `none`, which does not perform reasoning. The supported reasoning values for `gpt-5.1` are `none`, `low`, `medium`, and `high`. Tool calls are supported for all reasoning values in gpt-5.1. - - All models before `gpt-5.1` default to `medium` reasoning effort, and do not support `none`. - - The `gpt-5-pro` model defaults to (and only supports) `high` reasoning effort. - - `xhigh` is supported for all models after `gpt-5.1-codex-max`. + Constrains effort on reasoning for reasoning models. Currently supported + values are `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max`. + Reducing reasoning effort can result in faster responses and fewer tokens + used on reasoning in a response. Not all reasoning models support every + value. See the + [reasoning guide](https://platform.openai.com/docs/guides/reasoning) + for model-specific support. - `:none` @@ -8788,6 +9804,8 @@ as input for the model's response. - `:xhigh` + - `:max` + - `generate_summary: :auto | :concise | :detailed` **Deprecated:** use `summary` instead. @@ -8802,6 +9820,24 @@ as input for the model's response. - `:detailed` + - `mode: String | :standard | :pro` + + Controls the reasoning execution mode for the request. + + When returned on a response, this is the effective execution mode. + + - `String = String` + + - `Mode = :standard | :pro` + + Controls the reasoning execution mode for the request. + + When returned on a response, this is the effective execution mode. + + - `:standard` + + - `:pro` + - `summary: :auto | :concise | :detailed` A summary of the reasoning performed by the model. This can be @@ -8982,10 +10018,14 @@ as input for the model's response. The number of input tokens. - - `input_tokens_details: InputTokensDetails{ cached_tokens}` + - `input_tokens_details: InputTokensDetails{ cache_write_tokens, cached_tokens}` A detailed breakdown of the input tokens. + - `cache_write_tokens: Integer` + + The number of input tokens that were written to the cache. + - `cached_tokens: Integer` The number of tokens that were retrieved from the cache. @@ -9096,8 +10136,14 @@ puts(response) }, "strict": true, "type": "function", + "allowed_callers": [ + "direct" + ], "defer_loading": true, - "description": "description" + "description": "description", + "output_schema": { + "foo": "bar" + } } ], "top_p": 1, @@ -9152,11 +10198,16 @@ puts(response) "version": "version" }, "prompt_cache_key": "prompt-cache-key-1234", + "prompt_cache_options": { + "mode": "implicit", + "ttl": "30m" + }, "prompt_cache_retention": "in_memory", "reasoning": { "context": "auto", "effort": "none", "generate_summary": "auto", + "mode": "standard", "summary": "auto" }, "safety_identifier": "safety-identifier-1234", @@ -9173,6 +10224,7 @@ puts(response) "usage": { "input_tokens": 0, "input_tokens_details": { + "cache_write_tokens": 0, "cached_tokens": 0 }, "output_tokens": 0, @@ -9191,7 +10243,7 @@ puts(response) **get** `/responses/{response_id}` -Retrieves a model response with the given ID. +Get a model response ### Parameters @@ -9255,7 +10307,7 @@ Retrieves a model response with the given ID. An error object returned when the model fails to generate a Response. - - `code: :server_error | :rate_limit_exceeded | :invalid_prompt | 15 more` + - `code: :server_error | :rate_limit_exceeded | :invalid_prompt | 16 more` The error code for the response. @@ -9265,6 +10317,8 @@ Retrieves a model response with the given ID. - `:invalid_prompt` + - `:bio_policy` + - `:vector_store_timeout` - `:invalid_image` @@ -9365,6 +10419,16 @@ Retrieves a model response with the given ID. - `:input_text` + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + + 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`. + + - `:explicit` + - `class ResponseInputImage` An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). @@ -9395,6 +10459,16 @@ Retrieves a model response with the given ID. The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + + 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`. + + - `:explicit` + - `class ResponseInputFile` A file input to the model. @@ -9405,9 +10479,11 @@ Retrieves a model response with the given ID. - `:input_file` - - `detail: :low | :high` + - `detail: :auto | :low | :high` - The detail level of the file to be sent to the model. Use `low` for the default rendering behavior, or `high` to render the file at higher quality. Defaults to `low`. + The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. + + - `:auto` - `:low` @@ -9429,6 +10505,16 @@ Retrieves a model response with the given ID. The name of the file to be sent to the model. + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + + 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`. + + - `:explicit` + - `role: :user | :assistant | :system | :developer` The role of the message input. One of `user`, `assistant`, `system`, or @@ -10376,6 +11462,26 @@ Retrieves a model response with the given ID. The unique ID of the function tool call. + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + - `:program` + - `namespace: String` The namespace of the function to run. @@ -10425,6 +11531,16 @@ Retrieves a model response with the given ID. - `:input_text` + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + + 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`. + + - `:explicit` + - `class ResponseInputImageContent` An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) @@ -10455,6 +11571,16 @@ Retrieves a model response with the given ID. The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + + 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`. + + - `:explicit` + - `class ResponseInputFileContent` A file input to the model. @@ -10465,9 +11591,11 @@ Retrieves a model response with the given ID. - `:input_file` - - `detail: :low | :high` + - `detail: :auto | :low | :high` - The detail level of the file to be sent to the model. Use `low` for the default rendering behavior, or `high` to render the file at higher quality. Defaults to `low`. + The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. + + - `:auto` - `:low` @@ -10489,6 +11617,16 @@ Retrieves a model response with the given ID. The name of the file to be sent to the model. + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + + 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`. + + - `:explicit` + - `type: :function_call_output` The type of the function tool call output. Always `function_call_output`. @@ -10499,6 +11637,30 @@ Retrieves a model response with the given ID. The unique ID of the function tool call output. Populated when this item is returned via API. + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + The caller type. Always `direct`. + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + The caller type. Always `program`. + + - `:program` + - `status: :in_progress | :completed | :incomplete` The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. @@ -10567,7 +11729,7 @@ Retrieves a model response with the given ID. - `strict: bool` - Whether to enforce strict parameter validation. Default `true`. + Whether strict parameter validation is enforced for this function tool. - `type: :function` @@ -10575,6 +11737,14 @@ Retrieves a model response with the given ID. - `:function` + - `allowed_callers: Array[:direct | :programmatic]` + + The tool invocation context(s). + + - `:direct` + + - `:programmatic` + - `defer_loading: bool` Whether this function is deferred and loaded via tool search. @@ -10583,6 +11753,10 @@ Retrieves a model response with the given ID. A description of the function. Used by the model to determine whether or not to call the function. + - `output_schema: Hash[Symbol, untyped]` + + A JSON schema object describing the JSON value encoded in string outputs for this function. + - `class FileSearchTool` A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). @@ -10638,7 +11812,7 @@ Retrieves a model response with the given ID. - `:nin` - - `value: String | Float | bool | Array[String | Float]` + - `value: String | Float | bool | Array[untyped]` The value to compare against the attribute key; supports string, number, or boolean types. @@ -10648,11 +11822,7 @@ Retrieves a model response with the given ID. - `UnionMember2 = bool` - - `UnionMember3 = Array[String | Float]` - - - `String = String` - - - `Float = Float` + - `UnionMember3 = Array[untyped]` - `class CompoundFilter` @@ -10825,6 +11995,14 @@ Retrieves a model response with the given ID. - `:mcp` + - `allowed_callers: Array[:direct | :programmatic]` + + The tool invocation context(s). + + - `:direct` + + - `:programmatic` + - `allowed_tools: Array[String] | McpToolFilter{ read_only, tool_names}` List of allowed tool names or a filter object. @@ -11043,6 +12221,22 @@ Retrieves a model response with the given ID. - `:code_interpreter` + - `allowed_callers: Array[:direct | :programmatic]` + + The tool invocation context(s). + + - `:direct` + + - `:programmatic` + + - `class ProgrammaticToolCalling` + + - `type: :programmatic_tool_calling` + + The type of the tool. Always `programmatic_tool_calling`. + + - `:programmatic_tool_calling` + - `class ImageGeneration` A tool that generates images using the GPT image models. @@ -11206,6 +12400,14 @@ Retrieves a model response with the given ID. - `:shell` + - `allowed_callers: Array[:direct | :programmatic]` + + The tool invocation context(s). + + - `:direct` + + - `:programmatic` + - `environment: ContainerAuto | LocalEnvironment | ContainerReference` - `class ContainerAuto` @@ -11346,6 +12548,14 @@ Retrieves a model response with the given ID. - `:custom` + - `allowed_callers: Array[:direct | :programmatic]` + + The tool invocation context(s). + + - `:direct` + + - `:programmatic` + - `defer_loading: bool` Whether this tool should be deferred and discovered via tool search. @@ -11402,7 +12612,7 @@ Retrieves a model response with the given ID. The namespace name used in tool calls (for example, `crm`). - - `tools: Array[Function{ name, type, defer_loading, 3 more} | CustomTool]` + - `tools: Array[Function{ name, type, allowed_callers, 5 more} | CustomTool]` The function/custom tools available inside this namespace. @@ -11414,16 +12624,30 @@ Retrieves a model response with the given ID. - `:function` + - `allowed_callers: Array[:direct | :programmatic]` + + The tool invocation context(s). + + - `:direct` + + - `:programmatic` + - `defer_loading: bool` Whether this function should be deferred and discovered via tool search. - `description: String` + - `output_schema: Hash[Symbol, untyped]` + + A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. + - `parameters: untyped` - `strict: bool` + Whether to enforce strict parameter validation. If omitted, Responses attempts to use strict validation when the schema is compatible, and falls back to non-strict validation otherwise. + - `class CustomTool` A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) @@ -11524,6 +12748,14 @@ Retrieves a model response with the given ID. - `:apply_patch` + - `allowed_callers: Array[:direct | :programmatic]` + + The tool invocation context(s). + + - `:direct` + + - `:programmatic` + - `type: :tool_search_output` The item type. Always `tool_search_output`. @@ -11598,6 +12830,8 @@ Retrieves a model response with the given ID. A tool that runs Python code to help generate a response to a prompt. + - `class ProgrammaticToolCalling` + - `class ImageGeneration` A tool that generates images using the GPT image models. @@ -11938,6 +13172,30 @@ Retrieves a model response with the given ID. The unique ID of the shell tool call. Populated when this item is returned via API. + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + The caller type. Always `direct`. + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + The caller type. Always `program`. + + - `:program` + - `environment: LocalEnvironment | ContainerReference` The environment to execute the shell commands in. @@ -12014,6 +13272,30 @@ Retrieves a model response with the given ID. The unique ID of the shell tool call output. Populated when this item is returned via API. + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + The caller type. Always `direct`. + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + The caller type. Always `program`. + + - `:program` + - `max_output_length: Integer` The maximum number of UTF-8 characters captured for this shell call's combined output. @@ -12108,6 +13390,30 @@ Retrieves a model response with the given ID. The unique ID of the apply patch tool call. Populated when this item is returned via API. + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + The caller type. Always `direct`. + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + The caller type. Always `program`. + + - `:program` + - `class ApplyPatchCallOutput` The streamed output emitted by an apply patch tool call. @@ -12134,6 +13440,30 @@ Retrieves a model response with the given ID. The unique ID of the apply patch tool call output. Populated when this item is returned via API. + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + The caller type. Always `direct`. + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + The caller type. Always `program`. + + - `:program` + - `output: String` Optional human-readable log text from the apply patch tool (e.g., patch results or errors). @@ -12328,6 +13658,30 @@ Retrieves a model response with the given ID. The unique ID of the custom tool call output in the OpenAI platform. + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + The caller type. Always `direct`. + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + The caller type. Always `program`. + + - `:program` + - `class ResponseCustomToolCall` A call to a custom tool created by the model. @@ -12354,6 +13708,26 @@ Retrieves a model response with the given ID. The unique ID of the custom tool call in the OpenAI platform. + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + - `:program` + - `namespace: String` The namespace of the custom tool being called. @@ -12382,6 +13756,58 @@ Retrieves a model response with the given ID. - `:item_reference` + - `class Program` + + - `id: String` + + The unique ID of this program item. + + - `call_id: String` + + The stable call ID of the program item. + + - `code: String` + + The JavaScript source executed by programmatic tool calling. + + - `fingerprint: String` + + Opaque program replay fingerprint that must be round-tripped. + + - `type: :program` + + The item type. Always `program`. + + - `:program` + + - `class ProgramOutput` + + - `id: String` + + The unique ID of this program output item. + + - `call_id: String` + + The call ID of the program item. + + - `result: String` + + The result produced by the program item. + + - `status: :completed | :incomplete` + + The terminal status of the program output. + + - `:completed` + + - `:incomplete` + + - `type: :program_output` + + The item type. Always `program_output`. + + - `:program_output` + - `metadata: Metadata` Set of 16 key-value pairs that can be attached to an object. This can be @@ -12400,7 +13826,13 @@ Retrieves a model response with the given ID. - `String = String` - - `ChatModel = :"gpt-5.4" | :"gpt-5.4-mini" | :"gpt-5.4-nano" | 75 more` + - `ChatModel = :"gpt-5.6-sol" | :"gpt-5.6-terra" | :"gpt-5.6-luna" | 78 more` + + - `:"gpt-5.6-sol"` + + - `:"gpt-5.6-terra"` + + - `:"gpt-5.6-luna"` - `:"gpt-5.4"` @@ -12671,6 +14103,30 @@ Retrieves a model response with the given ID. - `:function_call_output` + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + The caller type. Always `direct`. + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + The caller type. Always `program`. + + - `:program` + - `created_by: String` The identifier of the actor that created the item. @@ -12746,6 +14202,58 @@ Retrieves a model response with the given ID. for subsequent turns of a conversation if you are manually [managing context](https://platform.openai.com/docs/guides/conversation-state). + - `class Program` + + - `id: String` + + The unique ID of the program item. + + - `call_id: String` + + The stable call ID of the program item. + + - `code: String` + + The JavaScript source executed by programmatic tool calling. + + - `fingerprint: String` + + Opaque program replay fingerprint that must be round-tripped. + + - `type: :program` + + The type of the item. Always `program`. + + - `:program` + + - `class ProgramOutput` + + - `id: String` + + The unique ID of the program output item. + + - `call_id: String` + + The call ID of the program item. + + - `result: String` + + The result produced by the program item. + + - `status: :completed | :incomplete` + + The terminal status of the program output item. + + - `:completed` + + - `:incomplete` + + - `type: :program_output` + + The type of the item. Always `program_output`. + + - `:program_output` + - `class ResponseToolSearchCall` - `id: String` @@ -12850,6 +14358,8 @@ Retrieves a model response with the given ID. A tool that runs Python code to help generate a response to a prompt. + - `class ProgrammaticToolCalling` + - `class ImageGeneration` A tool that generates images using the GPT image models. @@ -12952,6 +14462,8 @@ Retrieves a model response with the given ID. A tool that runs Python code to help generate a response to a prompt. + - `class ProgrammaticToolCalling` + - `class ImageGeneration` A tool that generates images using the GPT image models. @@ -13200,6 +14712,26 @@ Retrieves a model response with the given ID. - `:shell_call` + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + - `:program` + - `created_by: String` The ID of the entity that created this tool call. @@ -13280,6 +14812,26 @@ Retrieves a model response with the given ID. - `:shell_call_output` + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + - `:program` + - `created_by: String` The identifier of the actor that created the item. @@ -13364,6 +14916,26 @@ Retrieves a model response with the given ID. - `:apply_patch_call` + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + - `:program` + - `created_by: String` The ID of the entity that created this tool call. @@ -13394,6 +14966,26 @@ Retrieves a model response with the given ID. - `:apply_patch_call_output` + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + - `:program` + - `created_by: String` The ID of the entity that created this tool call output. @@ -13585,7 +15177,7 @@ Retrieves a model response with the given ID. What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. We generally recommend altering this or `top_p` but not both. - - `tool_choice: ToolChoiceOptions | ToolChoiceAllowed | ToolChoiceTypes | 5 more` + - `tool_choice: ToolChoiceOptions | ToolChoiceAllowed | ToolChoiceTypes | 6 more` How the model should select which tool (or tools) to use when generating a response. See the `tools` parameter to see how to specify which tools @@ -13727,6 +15319,14 @@ Retrieves a model response with the given ID. - `:custom` + - `class SpecificProgrammaticToolCallingParam` + + - `type: :programmatic_tool_calling` + + The tool to call. Always `programmatic_tool_calling`. + + - `:programmatic_tool_calling` + - `class ToolChoiceApplyPatch` Forces the model to call the apply_patch tool when executing a tool call. @@ -13797,6 +15397,8 @@ Retrieves a model response with the given ID. A tool that runs Python code to help generate a response to a prompt. + - `class ProgrammaticToolCalling` + - `class ImageGeneration` A tool that generates images using the GPT image models. @@ -14023,9 +15625,32 @@ Retrieves a model response with the given ID. Used by OpenAI to cache responses for similar requests to optimize your cache hit rates. Replaces the `user` field. [Learn more](https://platform.openai.com/docs/guides/prompt-caching). + - `prompt_cache_options: PromptCacheOptions{ mode, ttl}` + + The prompt-caching options that were applied to the response. Supported for `gpt-5.6` and later models. + + - `mode: :implicit | :explicit` + + Whether implicit prompt-cache breakpoints were enabled. + + - `:implicit` + + - `:explicit` + + - `ttl: :"30m"` + + The minimum lifetime applied to each cache breakpoint. + + - `:"30m"` + - `prompt_cache_retention: :in_memory | :"24h"` + Deprecated. Use `prompt_cache_options.ttl` instead. + The retention policy for the prompt cache. Set to `24h` to enable extended prompt caching, which keeps cached prefixes active for longer, up to a maximum of 24 hours. [Learn more](https://platform.openai.com/docs/guides/prompt-caching#prompt-cache-retention). + This field expresses a maximum retention policy, while + `prompt_cache_options.ttl` expresses a minimum cache lifetime. The two + fields are independent and do not interact. For `gpt-5.5`, `gpt-5.5-pro`, and future models, only `24h` is supported. For older models that support both `in_memory` and `24h`, the default depends on your organization's data retention policy: @@ -14058,16 +15683,13 @@ Retrieves a model response with the given ID. - `effort: ReasoningEffort` - Constrains effort on reasoning for - [reasoning models](https://platform.openai.com/docs/guides/reasoning). - Currently supported values are `none`, `minimal`, `low`, `medium`, `high`, and `xhigh`. Reducing - reasoning effort can result in faster responses and fewer tokens used - on reasoning in a response. - - - `gpt-5.1` defaults to `none`, which does not perform reasoning. The supported reasoning values for `gpt-5.1` are `none`, `low`, `medium`, and `high`. Tool calls are supported for all reasoning values in gpt-5.1. - - All models before `gpt-5.1` default to `medium` reasoning effort, and do not support `none`. - - The `gpt-5-pro` model defaults to (and only supports) `high` reasoning effort. - - `xhigh` is supported for all models after `gpt-5.1-codex-max`. + Constrains effort on reasoning for reasoning models. Currently supported + values are `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max`. + Reducing reasoning effort can result in faster responses and fewer tokens + used on reasoning in a response. Not all reasoning models support every + value. See the + [reasoning guide](https://platform.openai.com/docs/guides/reasoning) + for model-specific support. - `:none` @@ -14081,6 +15703,8 @@ Retrieves a model response with the given ID. - `:xhigh` + - `:max` + - `generate_summary: :auto | :concise | :detailed` **Deprecated:** use `summary` instead. @@ -14095,6 +15719,24 @@ Retrieves a model response with the given ID. - `:detailed` + - `mode: String | :standard | :pro` + + Controls the reasoning execution mode for the request. + + When returned on a response, this is the effective execution mode. + + - `String = String` + + - `Mode = :standard | :pro` + + Controls the reasoning execution mode for the request. + + When returned on a response, this is the effective execution mode. + + - `:standard` + + - `:pro` + - `summary: :auto | :concise | :detailed` A summary of the reasoning performed by the model. This can be @@ -14275,10 +15917,14 @@ Retrieves a model response with the given ID. The number of input tokens. - - `input_tokens_details: InputTokensDetails{ cached_tokens}` + - `input_tokens_details: InputTokensDetails{ cache_write_tokens, cached_tokens}` A detailed breakdown of the input tokens. + - `cache_write_tokens: Integer` + + The number of input tokens that were written to the cache. + - `cached_tokens: Integer` The number of tokens that were retrieved from the cache. @@ -14389,8 +16035,14 @@ puts(response) }, "strict": true, "type": "function", + "allowed_callers": [ + "direct" + ], "defer_loading": true, - "description": "description" + "description": "description", + "output_schema": { + "foo": "bar" + } } ], "top_p": 1, @@ -14445,11 +16097,16 @@ puts(response) "version": "version" }, "prompt_cache_key": "prompt-cache-key-1234", + "prompt_cache_options": { + "mode": "implicit", + "ttl": "30m" + }, "prompt_cache_retention": "in_memory", "reasoning": { "context": "auto", "effort": "none", "generate_summary": "auto", + "mode": "standard", "summary": "auto" }, "safety_identifier": "safety-identifier-1234", @@ -14466,6 +16123,7 @@ puts(response) "usage": { "input_tokens": 0, "input_tokens_details": { + "cache_write_tokens": 0, "cached_tokens": 0 }, "output_tokens": 0, @@ -14484,7 +16142,7 @@ puts(response) **delete** `/responses/{response_id}` -Deletes a model response with the given ID. +Delete a model response ### Parameters @@ -14508,9 +16166,7 @@ puts(result) **post** `/responses/{response_id}/cancel` -Cancels a model response with the given ID. Only responses created with -the `background` parameter set to `true` can be cancelled. -[Learn more](https://platform.openai.com/docs/guides/background). +Cancel a response ### Parameters @@ -14532,7 +16188,7 @@ the `background` parameter set to `true` can be cancelled. An error object returned when the model fails to generate a Response. - - `code: :server_error | :rate_limit_exceeded | :invalid_prompt | 15 more` + - `code: :server_error | :rate_limit_exceeded | :invalid_prompt | 16 more` The error code for the response. @@ -14542,6 +16198,8 @@ the `background` parameter set to `true` can be cancelled. - `:invalid_prompt` + - `:bio_policy` + - `:vector_store_timeout` - `:invalid_image` @@ -14642,6 +16300,16 @@ the `background` parameter set to `true` can be cancelled. - `:input_text` + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + + 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`. + + - `:explicit` + - `class ResponseInputImage` An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). @@ -14672,6 +16340,16 @@ the `background` parameter set to `true` can be cancelled. The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + + 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`. + + - `:explicit` + - `class ResponseInputFile` A file input to the model. @@ -14682,9 +16360,11 @@ the `background` parameter set to `true` can be cancelled. - `:input_file` - - `detail: :low | :high` + - `detail: :auto | :low | :high` - The detail level of the file to be sent to the model. Use `low` for the default rendering behavior, or `high` to render the file at higher quality. Defaults to `low`. + The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. + + - `:auto` - `:low` @@ -14706,6 +16386,16 @@ the `background` parameter set to `true` can be cancelled. The name of the file to be sent to the model. + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + + 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`. + + - `:explicit` + - `role: :user | :assistant | :system | :developer` The role of the message input. One of `user`, `assistant`, `system`, or @@ -15653,6 +17343,26 @@ the `background` parameter set to `true` can be cancelled. The unique ID of the function tool call. + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + - `:program` + - `namespace: String` The namespace of the function to run. @@ -15702,6 +17412,16 @@ the `background` parameter set to `true` can be cancelled. - `:input_text` + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + + 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`. + + - `:explicit` + - `class ResponseInputImageContent` An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) @@ -15732,6 +17452,16 @@ the `background` parameter set to `true` can be cancelled. The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + + 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`. + + - `:explicit` + - `class ResponseInputFileContent` A file input to the model. @@ -15742,9 +17472,11 @@ the `background` parameter set to `true` can be cancelled. - `:input_file` - - `detail: :low | :high` + - `detail: :auto | :low | :high` + + The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. - The detail level of the file to be sent to the model. Use `low` for the default rendering behavior, or `high` to render the file at higher quality. Defaults to `low`. + - `:auto` - `:low` @@ -15766,6 +17498,16 @@ the `background` parameter set to `true` can be cancelled. The name of the file to be sent to the model. + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + + 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`. + + - `:explicit` + - `type: :function_call_output` The type of the function tool call output. Always `function_call_output`. @@ -15776,6 +17518,30 @@ the `background` parameter set to `true` can be cancelled. The unique ID of the function tool call output. Populated when this item is returned via API. + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + The caller type. Always `direct`. + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + The caller type. Always `program`. + + - `:program` + - `status: :in_progress | :completed | :incomplete` The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. @@ -15844,7 +17610,7 @@ the `background` parameter set to `true` can be cancelled. - `strict: bool` - Whether to enforce strict parameter validation. Default `true`. + Whether strict parameter validation is enforced for this function tool. - `type: :function` @@ -15852,6 +17618,14 @@ the `background` parameter set to `true` can be cancelled. - `:function` + - `allowed_callers: Array[:direct | :programmatic]` + + The tool invocation context(s). + + - `:direct` + + - `:programmatic` + - `defer_loading: bool` Whether this function is deferred and loaded via tool search. @@ -15860,6 +17634,10 @@ the `background` parameter set to `true` can be cancelled. A description of the function. Used by the model to determine whether or not to call the function. + - `output_schema: Hash[Symbol, untyped]` + + A JSON schema object describing the JSON value encoded in string outputs for this function. + - `class FileSearchTool` A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). @@ -15915,7 +17693,7 @@ the `background` parameter set to `true` can be cancelled. - `:nin` - - `value: String | Float | bool | Array[String | Float]` + - `value: String | Float | bool | Array[untyped]` The value to compare against the attribute key; supports string, number, or boolean types. @@ -15925,11 +17703,7 @@ the `background` parameter set to `true` can be cancelled. - `UnionMember2 = bool` - - `UnionMember3 = Array[String | Float]` - - - `String = String` - - - `Float = Float` + - `UnionMember3 = Array[untyped]` - `class CompoundFilter` @@ -16102,6 +17876,14 @@ the `background` parameter set to `true` can be cancelled. - `:mcp` + - `allowed_callers: Array[:direct | :programmatic]` + + The tool invocation context(s). + + - `:direct` + + - `:programmatic` + - `allowed_tools: Array[String] | McpToolFilter{ read_only, tool_names}` List of allowed tool names or a filter object. @@ -16320,6 +18102,22 @@ the `background` parameter set to `true` can be cancelled. - `:code_interpreter` + - `allowed_callers: Array[:direct | :programmatic]` + + The tool invocation context(s). + + - `:direct` + + - `:programmatic` + + - `class ProgrammaticToolCalling` + + - `type: :programmatic_tool_calling` + + The type of the tool. Always `programmatic_tool_calling`. + + - `:programmatic_tool_calling` + - `class ImageGeneration` A tool that generates images using the GPT image models. @@ -16483,6 +18281,14 @@ the `background` parameter set to `true` can be cancelled. - `:shell` + - `allowed_callers: Array[:direct | :programmatic]` + + The tool invocation context(s). + + - `:direct` + + - `:programmatic` + - `environment: ContainerAuto | LocalEnvironment | ContainerReference` - `class ContainerAuto` @@ -16623,6 +18429,14 @@ the `background` parameter set to `true` can be cancelled. - `:custom` + - `allowed_callers: Array[:direct | :programmatic]` + + The tool invocation context(s). + + - `:direct` + + - `:programmatic` + - `defer_loading: bool` Whether this tool should be deferred and discovered via tool search. @@ -16679,7 +18493,7 @@ the `background` parameter set to `true` can be cancelled. The namespace name used in tool calls (for example, `crm`). - - `tools: Array[Function{ name, type, defer_loading, 3 more} | CustomTool]` + - `tools: Array[Function{ name, type, allowed_callers, 5 more} | CustomTool]` The function/custom tools available inside this namespace. @@ -16691,16 +18505,30 @@ the `background` parameter set to `true` can be cancelled. - `:function` + - `allowed_callers: Array[:direct | :programmatic]` + + The tool invocation context(s). + + - `:direct` + + - `:programmatic` + - `defer_loading: bool` Whether this function should be deferred and discovered via tool search. - `description: String` + - `output_schema: Hash[Symbol, untyped]` + + A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. + - `parameters: untyped` - `strict: bool` + Whether to enforce strict parameter validation. If omitted, Responses attempts to use strict validation when the schema is compatible, and falls back to non-strict validation otherwise. + - `class CustomTool` A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) @@ -16801,6 +18629,14 @@ the `background` parameter set to `true` can be cancelled. - `:apply_patch` + - `allowed_callers: Array[:direct | :programmatic]` + + The tool invocation context(s). + + - `:direct` + + - `:programmatic` + - `type: :tool_search_output` The item type. Always `tool_search_output`. @@ -16875,6 +18711,8 @@ the `background` parameter set to `true` can be cancelled. A tool that runs Python code to help generate a response to a prompt. + - `class ProgrammaticToolCalling` + - `class ImageGeneration` A tool that generates images using the GPT image models. @@ -17215,6 +19053,30 @@ the `background` parameter set to `true` can be cancelled. The unique ID of the shell tool call. Populated when this item is returned via API. + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + The caller type. Always `direct`. + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + The caller type. Always `program`. + + - `:program` + - `environment: LocalEnvironment | ContainerReference` The environment to execute the shell commands in. @@ -17291,6 +19153,30 @@ the `background` parameter set to `true` can be cancelled. The unique ID of the shell tool call output. Populated when this item is returned via API. + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + The caller type. Always `direct`. + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + The caller type. Always `program`. + + - `:program` + - `max_output_length: Integer` The maximum number of UTF-8 characters captured for this shell call's combined output. @@ -17385,6 +19271,30 @@ the `background` parameter set to `true` can be cancelled. The unique ID of the apply patch tool call. Populated when this item is returned via API. + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + The caller type. Always `direct`. + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + The caller type. Always `program`. + + - `:program` + - `class ApplyPatchCallOutput` The streamed output emitted by an apply patch tool call. @@ -17411,6 +19321,30 @@ the `background` parameter set to `true` can be cancelled. The unique ID of the apply patch tool call output. Populated when this item is returned via API. + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + The caller type. Always `direct`. + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + The caller type. Always `program`. + + - `:program` + - `output: String` Optional human-readable log text from the apply patch tool (e.g., patch results or errors). @@ -17605,6 +19539,30 @@ the `background` parameter set to `true` can be cancelled. The unique ID of the custom tool call output in the OpenAI platform. + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + The caller type. Always `direct`. + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + The caller type. Always `program`. + + - `:program` + - `class ResponseCustomToolCall` A call to a custom tool created by the model. @@ -17631,6 +19589,26 @@ the `background` parameter set to `true` can be cancelled. The unique ID of the custom tool call in the OpenAI platform. + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + - `:program` + - `namespace: String` The namespace of the custom tool being called. @@ -17659,6 +19637,58 @@ the `background` parameter set to `true` can be cancelled. - `:item_reference` + - `class Program` + + - `id: String` + + The unique ID of this program item. + + - `call_id: String` + + The stable call ID of the program item. + + - `code: String` + + The JavaScript source executed by programmatic tool calling. + + - `fingerprint: String` + + Opaque program replay fingerprint that must be round-tripped. + + - `type: :program` + + The item type. Always `program`. + + - `:program` + + - `class ProgramOutput` + + - `id: String` + + The unique ID of this program output item. + + - `call_id: String` + + The call ID of the program item. + + - `result: String` + + The result produced by the program item. + + - `status: :completed | :incomplete` + + The terminal status of the program output. + + - `:completed` + + - `:incomplete` + + - `type: :program_output` + + The item type. Always `program_output`. + + - `:program_output` + - `metadata: Metadata` Set of 16 key-value pairs that can be attached to an object. This can be @@ -17677,7 +19707,13 @@ the `background` parameter set to `true` can be cancelled. - `String = String` - - `ChatModel = :"gpt-5.4" | :"gpt-5.4-mini" | :"gpt-5.4-nano" | 75 more` + - `ChatModel = :"gpt-5.6-sol" | :"gpt-5.6-terra" | :"gpt-5.6-luna" | 78 more` + + - `:"gpt-5.6-sol"` + + - `:"gpt-5.6-terra"` + + - `:"gpt-5.6-luna"` - `:"gpt-5.4"` @@ -17948,6 +19984,30 @@ the `background` parameter set to `true` can be cancelled. - `:function_call_output` + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + The caller type. Always `direct`. + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + The caller type. Always `program`. + + - `:program` + - `created_by: String` The identifier of the actor that created the item. @@ -18023,6 +20083,58 @@ the `background` parameter set to `true` can be cancelled. for subsequent turns of a conversation if you are manually [managing context](https://platform.openai.com/docs/guides/conversation-state). + - `class Program` + + - `id: String` + + The unique ID of the program item. + + - `call_id: String` + + The stable call ID of the program item. + + - `code: String` + + The JavaScript source executed by programmatic tool calling. + + - `fingerprint: String` + + Opaque program replay fingerprint that must be round-tripped. + + - `type: :program` + + The type of the item. Always `program`. + + - `:program` + + - `class ProgramOutput` + + - `id: String` + + The unique ID of the program output item. + + - `call_id: String` + + The call ID of the program item. + + - `result: String` + + The result produced by the program item. + + - `status: :completed | :incomplete` + + The terminal status of the program output item. + + - `:completed` + + - `:incomplete` + + - `type: :program_output` + + The type of the item. Always `program_output`. + + - `:program_output` + - `class ResponseToolSearchCall` - `id: String` @@ -18127,6 +20239,8 @@ the `background` parameter set to `true` can be cancelled. A tool that runs Python code to help generate a response to a prompt. + - `class ProgrammaticToolCalling` + - `class ImageGeneration` A tool that generates images using the GPT image models. @@ -18229,6 +20343,8 @@ the `background` parameter set to `true` can be cancelled. A tool that runs Python code to help generate a response to a prompt. + - `class ProgrammaticToolCalling` + - `class ImageGeneration` A tool that generates images using the GPT image models. @@ -18477,6 +20593,26 @@ the `background` parameter set to `true` can be cancelled. - `:shell_call` + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + - `:program` + - `created_by: String` The ID of the entity that created this tool call. @@ -18557,6 +20693,26 @@ the `background` parameter set to `true` can be cancelled. - `:shell_call_output` + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + - `:program` + - `created_by: String` The identifier of the actor that created the item. @@ -18641,6 +20797,26 @@ the `background` parameter set to `true` can be cancelled. - `:apply_patch_call` + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + - `:program` + - `created_by: String` The ID of the entity that created this tool call. @@ -18671,6 +20847,26 @@ the `background` parameter set to `true` can be cancelled. - `:apply_patch_call_output` + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + - `:program` + - `created_by: String` The ID of the entity that created this tool call output. @@ -18862,7 +21058,7 @@ the `background` parameter set to `true` can be cancelled. What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. We generally recommend altering this or `top_p` but not both. - - `tool_choice: ToolChoiceOptions | ToolChoiceAllowed | ToolChoiceTypes | 5 more` + - `tool_choice: ToolChoiceOptions | ToolChoiceAllowed | ToolChoiceTypes | 6 more` How the model should select which tool (or tools) to use when generating a response. See the `tools` parameter to see how to specify which tools @@ -19004,6 +21200,14 @@ the `background` parameter set to `true` can be cancelled. - `:custom` + - `class SpecificProgrammaticToolCallingParam` + + - `type: :programmatic_tool_calling` + + The tool to call. Always `programmatic_tool_calling`. + + - `:programmatic_tool_calling` + - `class ToolChoiceApplyPatch` Forces the model to call the apply_patch tool when executing a tool call. @@ -19074,6 +21278,8 @@ the `background` parameter set to `true` can be cancelled. A tool that runs Python code to help generate a response to a prompt. + - `class ProgrammaticToolCalling` + - `class ImageGeneration` A tool that generates images using the GPT image models. @@ -19300,9 +21506,32 @@ the `background` parameter set to `true` can be cancelled. Used by OpenAI to cache responses for similar requests to optimize your cache hit rates. Replaces the `user` field. [Learn more](https://platform.openai.com/docs/guides/prompt-caching). + - `prompt_cache_options: PromptCacheOptions{ mode, ttl}` + + The prompt-caching options that were applied to the response. Supported for `gpt-5.6` and later models. + + - `mode: :implicit | :explicit` + + Whether implicit prompt-cache breakpoints were enabled. + + - `:implicit` + + - `:explicit` + + - `ttl: :"30m"` + + The minimum lifetime applied to each cache breakpoint. + + - `:"30m"` + - `prompt_cache_retention: :in_memory | :"24h"` + Deprecated. Use `prompt_cache_options.ttl` instead. + The retention policy for the prompt cache. Set to `24h` to enable extended prompt caching, which keeps cached prefixes active for longer, up to a maximum of 24 hours. [Learn more](https://platform.openai.com/docs/guides/prompt-caching#prompt-cache-retention). + This field expresses a maximum retention policy, while + `prompt_cache_options.ttl` expresses a minimum cache lifetime. The two + fields are independent and do not interact. For `gpt-5.5`, `gpt-5.5-pro`, and future models, only `24h` is supported. For older models that support both `in_memory` and `24h`, the default depends on your organization's data retention policy: @@ -19335,16 +21564,13 @@ the `background` parameter set to `true` can be cancelled. - `effort: ReasoningEffort` - Constrains effort on reasoning for - [reasoning models](https://platform.openai.com/docs/guides/reasoning). - Currently supported values are `none`, `minimal`, `low`, `medium`, `high`, and `xhigh`. Reducing - reasoning effort can result in faster responses and fewer tokens used - on reasoning in a response. - - - `gpt-5.1` defaults to `none`, which does not perform reasoning. The supported reasoning values for `gpt-5.1` are `none`, `low`, `medium`, and `high`. Tool calls are supported for all reasoning values in gpt-5.1. - - All models before `gpt-5.1` default to `medium` reasoning effort, and do not support `none`. - - The `gpt-5-pro` model defaults to (and only supports) `high` reasoning effort. - - `xhigh` is supported for all models after `gpt-5.1-codex-max`. + Constrains effort on reasoning for reasoning models. Currently supported + values are `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max`. + Reducing reasoning effort can result in faster responses and fewer tokens + used on reasoning in a response. Not all reasoning models support every + value. See the + [reasoning guide](https://platform.openai.com/docs/guides/reasoning) + for model-specific support. - `:none` @@ -19358,6 +21584,8 @@ the `background` parameter set to `true` can be cancelled. - `:xhigh` + - `:max` + - `generate_summary: :auto | :concise | :detailed` **Deprecated:** use `summary` instead. @@ -19372,6 +21600,24 @@ the `background` parameter set to `true` can be cancelled. - `:detailed` + - `mode: String | :standard | :pro` + + Controls the reasoning execution mode for the request. + + When returned on a response, this is the effective execution mode. + + - `String = String` + + - `Mode = :standard | :pro` + + Controls the reasoning execution mode for the request. + + When returned on a response, this is the effective execution mode. + + - `:standard` + + - `:pro` + - `summary: :auto | :concise | :detailed` A summary of the reasoning performed by the model. This can be @@ -19552,10 +21798,14 @@ the `background` parameter set to `true` can be cancelled. The number of input tokens. - - `input_tokens_details: InputTokensDetails{ cached_tokens}` + - `input_tokens_details: InputTokensDetails{ cache_write_tokens, cached_tokens}` A detailed breakdown of the input tokens. + - `cache_write_tokens: Integer` + + The number of input tokens that were written to the cache. + - `cached_tokens: Integer` The number of tokens that were retrieved from the cache. @@ -19666,8 +21916,14 @@ puts(response) }, "strict": true, "type": "function", + "allowed_callers": [ + "direct" + ], "defer_loading": true, - "description": "description" + "description": "description", + "output_schema": { + "foo": "bar" + } } ], "top_p": 1, @@ -19722,11 +21978,16 @@ puts(response) "version": "version" }, "prompt_cache_key": "prompt-cache-key-1234", + "prompt_cache_options": { + "mode": "implicit", + "ttl": "30m" + }, "prompt_cache_retention": "in_memory", "reasoning": { "context": "auto", "effort": "none", "generate_summary": "auto", + "mode": "standard", "summary": "auto" }, "safety_identifier": "safety-identifier-1234", @@ -19743,6 +22004,7 @@ puts(response) "usage": { "input_tokens": 0, "input_tokens_details": { + "cache_write_tokens": 0, "cached_tokens": 0 }, "output_tokens": 0, @@ -19761,20 +22023,24 @@ puts(response) **post** `/responses/compact` -Compact a conversation. Returns a compacted response object. - -Learn when and how to compact long-running conversations in the [conversation state guide](https://platform.openai.com/docs/guides/conversation-state#managing-the-context-window). For ZDR-compatible compaction details, see [Compaction (advanced)](https://platform.openai.com/docs/guides/conversation-state#compaction-advanced). +Compact a response ### Parameters -- `model: :"gpt-5.4" | :"gpt-5.4-mini" | :"gpt-5.4-nano" | 89 more | String` +- `model: :"gpt-5.6-sol" | :"gpt-5.6-terra" | :"gpt-5.6-luna" | 92 more | String` Model ID used to generate the response, like `gpt-5` or `o3`. OpenAI offers a wide range of models with different capabilities, performance characteristics, and price points. Refer to the [model guide](https://platform.openai.com/docs/models) to browse and compare available models. - - `Model = :"gpt-5.4" | :"gpt-5.4-mini" | :"gpt-5.4-nano" | 89 more` + - `Model = :"gpt-5.6-sol" | :"gpt-5.6-terra" | :"gpt-5.6-luna" | 92 more` Model ID used to generate the response, like `gpt-5` or `o3`. OpenAI offers a wide range of models with different capabilities, performance characteristics, and price points. Refer to the [model guide](https://platform.openai.com/docs/models) to browse and compare available models. + - `:"gpt-5.6-sol"` + + - `:"gpt-5.6-terra"` + + - `:"gpt-5.6-luna"` + - `:"gpt-5.4"` - `:"gpt-5.4-mini"` @@ -20009,6 +22275,16 @@ Learn when and how to compact long-running conversations in the [conversation st - `:input_text` + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + + 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`. + + - `:explicit` + - `class ResponseInputImage` An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). @@ -20039,6 +22315,16 @@ Learn when and how to compact long-running conversations in the [conversation st The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + + 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`. + + - `:explicit` + - `class ResponseInputFile` A file input to the model. @@ -20049,9 +22335,11 @@ Learn when and how to compact long-running conversations in the [conversation st - `:input_file` - - `detail: :low | :high` + - `detail: :auto | :low | :high` - The detail level of the file to be sent to the model. Use `low` for the default rendering behavior, or `high` to render the file at higher quality. Defaults to `low`. + The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. + + - `:auto` - `:low` @@ -20073,6 +22361,16 @@ Learn when and how to compact long-running conversations in the [conversation st The name of the file to be sent to the model. + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + + 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`. + + - `:explicit` + - `role: :user | :assistant | :system | :developer` The role of the message input. One of `user`, `assistant`, `system`, or @@ -21020,6 +23318,26 @@ Learn when and how to compact long-running conversations in the [conversation st The unique ID of the function tool call. + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + - `:program` + - `namespace: String` The namespace of the function to run. @@ -21069,6 +23387,16 @@ Learn when and how to compact long-running conversations in the [conversation st - `:input_text` + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + + 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`. + + - `:explicit` + - `class ResponseInputImageContent` An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) @@ -21099,6 +23427,16 @@ Learn when and how to compact long-running conversations in the [conversation st The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + + 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`. + + - `:explicit` + - `class ResponseInputFileContent` A file input to the model. @@ -21109,9 +23447,11 @@ Learn when and how to compact long-running conversations in the [conversation st - `:input_file` - - `detail: :low | :high` + - `detail: :auto | :low | :high` + + The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. - The detail level of the file to be sent to the model. Use `low` for the default rendering behavior, or `high` to render the file at higher quality. Defaults to `low`. + - `:auto` - `:low` @@ -21133,6 +23473,16 @@ Learn when and how to compact long-running conversations in the [conversation st The name of the file to be sent to the model. + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + + 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`. + + - `:explicit` + - `type: :function_call_output` The type of the function tool call output. Always `function_call_output`. @@ -21143,6 +23493,30 @@ Learn when and how to compact long-running conversations in the [conversation st The unique ID of the function tool call output. Populated when this item is returned via API. + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + The caller type. Always `direct`. + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + The caller type. Always `program`. + + - `:program` + - `status: :in_progress | :completed | :incomplete` The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. @@ -21211,7 +23585,7 @@ Learn when and how to compact long-running conversations in the [conversation st - `strict: bool` - Whether to enforce strict parameter validation. Default `true`. + Whether strict parameter validation is enforced for this function tool. - `type: :function` @@ -21219,6 +23593,14 @@ Learn when and how to compact long-running conversations in the [conversation st - `:function` + - `allowed_callers: Array[:direct | :programmatic]` + + The tool invocation context(s). + + - `:direct` + + - `:programmatic` + - `defer_loading: bool` Whether this function is deferred and loaded via tool search. @@ -21227,6 +23609,10 @@ Learn when and how to compact long-running conversations in the [conversation st A description of the function. Used by the model to determine whether or not to call the function. + - `output_schema: Hash[Symbol, untyped]` + + A JSON schema object describing the JSON value encoded in string outputs for this function. + - `class FileSearchTool` A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). @@ -21282,7 +23668,7 @@ Learn when and how to compact long-running conversations in the [conversation st - `:nin` - - `value: String | Float | bool | Array[String | Float]` + - `value: String | Float | bool | Array[untyped]` The value to compare against the attribute key; supports string, number, or boolean types. @@ -21292,11 +23678,7 @@ Learn when and how to compact long-running conversations in the [conversation st - `UnionMember2 = bool` - - `UnionMember3 = Array[String | Float]` - - - `String = String` - - - `Float = Float` + - `UnionMember3 = Array[untyped]` - `class CompoundFilter` @@ -21469,6 +23851,14 @@ Learn when and how to compact long-running conversations in the [conversation st - `:mcp` + - `allowed_callers: Array[:direct | :programmatic]` + + The tool invocation context(s). + + - `:direct` + + - `:programmatic` + - `allowed_tools: Array[String] | McpToolFilter{ read_only, tool_names}` List of allowed tool names or a filter object. @@ -21687,6 +24077,22 @@ Learn when and how to compact long-running conversations in the [conversation st - `:code_interpreter` + - `allowed_callers: Array[:direct | :programmatic]` + + The tool invocation context(s). + + - `:direct` + + - `:programmatic` + + - `class ProgrammaticToolCalling` + + - `type: :programmatic_tool_calling` + + The type of the tool. Always `programmatic_tool_calling`. + + - `:programmatic_tool_calling` + - `class ImageGeneration` A tool that generates images using the GPT image models. @@ -21850,6 +24256,14 @@ Learn when and how to compact long-running conversations in the [conversation st - `:shell` + - `allowed_callers: Array[:direct | :programmatic]` + + The tool invocation context(s). + + - `:direct` + + - `:programmatic` + - `environment: ContainerAuto | LocalEnvironment | ContainerReference` - `class ContainerAuto` @@ -21990,6 +24404,14 @@ Learn when and how to compact long-running conversations in the [conversation st - `:custom` + - `allowed_callers: Array[:direct | :programmatic]` + + The tool invocation context(s). + + - `:direct` + + - `:programmatic` + - `defer_loading: bool` Whether this tool should be deferred and discovered via tool search. @@ -22046,7 +24468,7 @@ Learn when and how to compact long-running conversations in the [conversation st The namespace name used in tool calls (for example, `crm`). - - `tools: Array[Function{ name, type, defer_loading, 3 more} | CustomTool]` + - `tools: Array[Function{ name, type, allowed_callers, 5 more} | CustomTool]` The function/custom tools available inside this namespace. @@ -22058,16 +24480,30 @@ Learn when and how to compact long-running conversations in the [conversation st - `:function` + - `allowed_callers: Array[:direct | :programmatic]` + + The tool invocation context(s). + + - `:direct` + + - `:programmatic` + - `defer_loading: bool` Whether this function should be deferred and discovered via tool search. - `description: String` + - `output_schema: Hash[Symbol, untyped]` + + A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. + - `parameters: untyped` - `strict: bool` + Whether to enforce strict parameter validation. If omitted, Responses attempts to use strict validation when the schema is compatible, and falls back to non-strict validation otherwise. + - `class CustomTool` A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) @@ -22168,6 +24604,14 @@ Learn when and how to compact long-running conversations in the [conversation st - `:apply_patch` + - `allowed_callers: Array[:direct | :programmatic]` + + The tool invocation context(s). + + - `:direct` + + - `:programmatic` + - `type: :tool_search_output` The item type. Always `tool_search_output`. @@ -22242,6 +24686,8 @@ Learn when and how to compact long-running conversations in the [conversation st A tool that runs Python code to help generate a response to a prompt. + - `class ProgrammaticToolCalling` + - `class ImageGeneration` A tool that generates images using the GPT image models. @@ -22582,6 +25028,30 @@ Learn when and how to compact long-running conversations in the [conversation st The unique ID of the shell tool call. Populated when this item is returned via API. + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + The caller type. Always `direct`. + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + The caller type. Always `program`. + + - `:program` + - `environment: LocalEnvironment | ContainerReference` The environment to execute the shell commands in. @@ -22658,6 +25128,30 @@ Learn when and how to compact long-running conversations in the [conversation st The unique ID of the shell tool call output. Populated when this item is returned via API. + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + The caller type. Always `direct`. + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + The caller type. Always `program`. + + - `:program` + - `max_output_length: Integer` The maximum number of UTF-8 characters captured for this shell call's combined output. @@ -22752,6 +25246,30 @@ Learn when and how to compact long-running conversations in the [conversation st The unique ID of the apply patch tool call. Populated when this item is returned via API. + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + The caller type. Always `direct`. + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + The caller type. Always `program`. + + - `:program` + - `class ApplyPatchCallOutput` The streamed output emitted by an apply patch tool call. @@ -22778,6 +25296,30 @@ Learn when and how to compact long-running conversations in the [conversation st The unique ID of the apply patch tool call output. Populated when this item is returned via API. + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + The caller type. Always `direct`. + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + The caller type. Always `program`. + + - `:program` + - `output: String` Optional human-readable log text from the apply patch tool (e.g., patch results or errors). @@ -22972,6 +25514,30 @@ Learn when and how to compact long-running conversations in the [conversation st The unique ID of the custom tool call output in the OpenAI platform. + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + The caller type. Always `direct`. + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + The caller type. Always `program`. + + - `:program` + - `class ResponseCustomToolCall` A call to a custom tool created by the model. @@ -22998,6 +25564,26 @@ Learn when and how to compact long-running conversations in the [conversation st The unique ID of the custom tool call in the OpenAI platform. + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + - `:program` + - `namespace: String` The namespace of the custom tool being called. @@ -23026,6 +25612,58 @@ Learn when and how to compact long-running conversations in the [conversation st - `:item_reference` + - `class Program` + + - `id: String` + + The unique ID of this program item. + + - `call_id: String` + + The stable call ID of the program item. + + - `code: String` + + The JavaScript source executed by programmatic tool calling. + + - `fingerprint: String` + + Opaque program replay fingerprint that must be round-tripped. + + - `type: :program` + + The item type. Always `program`. + + - `:program` + + - `class ProgramOutput` + + - `id: String` + + The unique ID of this program output item. + + - `call_id: String` + + The call ID of the program item. + + - `result: String` + + The result produced by the program item. + + - `status: :completed | :incomplete` + + The terminal status of the program output. + + - `:completed` + + - `:incomplete` + + - `type: :program_output` + + The item type. Always `program_output`. + + - `:program_output` + - `instructions: String` A system (or developer) message inserted into the model's context. @@ -23039,6 +25677,24 @@ Learn when and how to compact long-running conversations in the [conversation st A key to use when reading from or writing to the prompt cache. +- `prompt_cache_options: PromptCacheOptions{ mode, ttl}` + + 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](https://platform.openai.com/docs/guides/prompt-caching) for current details. + + - `mode: :implicit | :explicit` + + 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. + + - `:implicit` + + - `:explicit` + + - `ttl: :"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. + + - `:"30m"` + - `prompt_cache_retention: :in_memory | :"24h"` How long to retain a prompt cache entry created by this request. @@ -23365,6 +26021,26 @@ Learn when and how to compact long-running conversations in the [conversation st The unique ID of the function tool call. + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + - `:program` + - `namespace: String` The namespace of the function to run. @@ -23417,6 +26093,16 @@ Learn when and how to compact long-running conversations in the [conversation st - `:input_text` + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + + 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`. + + - `:explicit` + - `class ResponseInputImage` An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). @@ -23447,6 +26133,16 @@ Learn when and how to compact long-running conversations in the [conversation st The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + + 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`. + + - `:explicit` + - `class ResponseInputFile` A file input to the model. @@ -23457,9 +26153,11 @@ Learn when and how to compact long-running conversations in the [conversation st - `:input_file` - - `detail: :low | :high` + - `detail: :auto | :low | :high` - The detail level of the file to be sent to the model. Use `low` for the default rendering behavior, or `high` to render the file at higher quality. Defaults to `low`. + The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. + + - `:auto` - `:low` @@ -23481,6 +26179,16 @@ Learn when and how to compact long-running conversations in the [conversation st The name of the file to be sent to the model. + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + + 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`. + + - `:explicit` + - `status: :in_progress | :completed | :incomplete` The status of the item. One of `in_progress`, `completed`, or @@ -23498,6 +26206,30 @@ Learn when and how to compact long-running conversations in the [conversation st - `:function_call_output` + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + The caller type. Always `direct`. + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + The caller type. Always `program`. + + - `:program` + - `created_by: String` The identifier of the actor that created the item. @@ -24165,6 +26897,58 @@ Learn when and how to compact long-running conversations in the [conversation st - `:incomplete` + - `class Program` + + - `id: String` + + The unique ID of the program item. + + - `call_id: String` + + The stable call ID of the program item. + + - `code: String` + + The JavaScript source executed by programmatic tool calling. + + - `fingerprint: String` + + Opaque program replay fingerprint that must be round-tripped. + + - `type: :program` + + The type of the item. Always `program`. + + - `:program` + + - `class ProgramOutput` + + - `id: String` + + The unique ID of the program output item. + + - `call_id: String` + + The call ID of the program item. + + - `result: String` + + The result produced by the program item. + + - `status: :completed | :incomplete` + + The terminal status of the program output item. + + - `:completed` + + - `:incomplete` + + - `type: :program_output` + + The type of the item. Always `program_output`. + + - `:program_output` + - `class ResponseToolSearchCall` - `id: String` @@ -24253,7 +27037,7 @@ Learn when and how to compact long-running conversations in the [conversation st - `strict: bool` - Whether to enforce strict parameter validation. Default `true`. + Whether strict parameter validation is enforced for this function tool. - `type: :function` @@ -24261,6 +27045,14 @@ Learn when and how to compact long-running conversations in the [conversation st - `:function` + - `allowed_callers: Array[:direct | :programmatic]` + + The tool invocation context(s). + + - `:direct` + + - `:programmatic` + - `defer_loading: bool` Whether this function is deferred and loaded via tool search. @@ -24269,6 +27061,10 @@ Learn when and how to compact long-running conversations in the [conversation st A description of the function. Used by the model to determine whether or not to call the function. + - `output_schema: Hash[Symbol, untyped]` + + A JSON schema object describing the JSON value encoded in string outputs for this function. + - `class FileSearchTool` A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). @@ -24324,7 +27120,7 @@ Learn when and how to compact long-running conversations in the [conversation st - `:nin` - - `value: String | Float | bool | Array[String | Float]` + - `value: String | Float | bool | Array[untyped]` The value to compare against the attribute key; supports string, number, or boolean types. @@ -24334,11 +27130,7 @@ Learn when and how to compact long-running conversations in the [conversation st - `UnionMember2 = bool` - - `UnionMember3 = Array[String | Float]` - - - `String = String` - - - `Float = Float` + - `UnionMember3 = Array[untyped]` - `class CompoundFilter` @@ -24511,6 +27303,14 @@ Learn when and how to compact long-running conversations in the [conversation st - `:mcp` + - `allowed_callers: Array[:direct | :programmatic]` + + The tool invocation context(s). + + - `:direct` + + - `:programmatic` + - `allowed_tools: Array[String] | McpToolFilter{ read_only, tool_names}` List of allowed tool names or a filter object. @@ -24729,6 +27529,22 @@ Learn when and how to compact long-running conversations in the [conversation st - `:code_interpreter` + - `allowed_callers: Array[:direct | :programmatic]` + + The tool invocation context(s). + + - `:direct` + + - `:programmatic` + + - `class ProgrammaticToolCalling` + + - `type: :programmatic_tool_calling` + + The type of the tool. Always `programmatic_tool_calling`. + + - `:programmatic_tool_calling` + - `class ImageGeneration` A tool that generates images using the GPT image models. @@ -24892,6 +27708,14 @@ Learn when and how to compact long-running conversations in the [conversation st - `:shell` + - `allowed_callers: Array[:direct | :programmatic]` + + The tool invocation context(s). + + - `:direct` + + - `:programmatic` + - `environment: ContainerAuto | LocalEnvironment | ContainerReference` - `class ContainerAuto` @@ -25032,6 +27856,14 @@ Learn when and how to compact long-running conversations in the [conversation st - `:custom` + - `allowed_callers: Array[:direct | :programmatic]` + + The tool invocation context(s). + + - `:direct` + + - `:programmatic` + - `defer_loading: bool` Whether this tool should be deferred and discovered via tool search. @@ -25088,7 +27920,7 @@ Learn when and how to compact long-running conversations in the [conversation st The namespace name used in tool calls (for example, `crm`). - - `tools: Array[Function{ name, type, defer_loading, 3 more} | CustomTool]` + - `tools: Array[Function{ name, type, allowed_callers, 5 more} | CustomTool]` The function/custom tools available inside this namespace. @@ -25100,16 +27932,30 @@ Learn when and how to compact long-running conversations in the [conversation st - `:function` + - `allowed_callers: Array[:direct | :programmatic]` + + The tool invocation context(s). + + - `:direct` + + - `:programmatic` + - `defer_loading: bool` Whether this function should be deferred and discovered via tool search. - `description: String` + - `output_schema: Hash[Symbol, untyped]` + + A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. + - `parameters: untyped` - `strict: bool` + Whether to enforce strict parameter validation. If omitted, Responses attempts to use strict validation when the schema is compatible, and falls back to non-strict validation otherwise. + - `class CustomTool` A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) @@ -25210,6 +28056,14 @@ Learn when and how to compact long-running conversations in the [conversation st - `:apply_patch` + - `allowed_callers: Array[:direct | :programmatic]` + + The tool invocation context(s). + + - `:direct` + + - `:programmatic` + - `type: :tool_search_output` The type of the item. Always `tool_search_output`. @@ -25280,6 +28134,8 @@ Learn when and how to compact long-running conversations in the [conversation st A tool that runs Python code to help generate a response to a prompt. + - `class ProgrammaticToolCalling` + - `class ImageGeneration` A tool that generates images using the GPT image models. @@ -25593,6 +28449,26 @@ Learn when and how to compact long-running conversations in the [conversation st - `:shell_call` + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + - `:program` + - `created_by: String` The ID of the entity that created this tool call. @@ -25673,6 +28549,26 @@ Learn when and how to compact long-running conversations in the [conversation st - `:shell_call_output` + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + - `:program` + - `created_by: String` The identifier of the actor that created the item. @@ -25757,6 +28653,26 @@ Learn when and how to compact long-running conversations in the [conversation st - `:apply_patch_call` + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + - `:program` + - `created_by: String` The ID of the entity that created this tool call. @@ -25787,6 +28703,26 @@ Learn when and how to compact long-running conversations in the [conversation st - `:apply_patch_call_output` + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + - `:program` + - `created_by: String` The ID of the entity that created this tool call output. @@ -25968,6 +28904,26 @@ Learn when and how to compact long-running conversations in the [conversation st The unique ID of the custom tool call in the OpenAI platform. + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + - `:program` + - `namespace: String` The namespace of the custom tool being called. @@ -26003,10 +28959,14 @@ Learn when and how to compact long-running conversations in the [conversation st The number of input tokens. - - `input_tokens_details: InputTokensDetails{ cached_tokens}` + - `input_tokens_details: InputTokensDetails{ cache_write_tokens, cached_tokens}` A detailed breakdown of the input tokens. + - `cache_write_tokens: Integer` + + The number of input tokens that were written to the cache. + - `cached_tokens: Integer` The number of tokens that were retrieved from the cache. @@ -26035,7 +28995,7 @@ require "openai" openai = OpenAI::Client.new(api_key: "My API Key") -compacted_response = openai.responses.compact(model: :"gpt-5.4") +compacted_response = openai.responses.compact(model: :"gpt-5.6-sol") puts(compacted_response) ``` @@ -26091,6 +29051,7 @@ puts(compacted_response) "usage": { "input_tokens": 0, "input_tokens_details": { + "cache_write_tokens": 0, "cached_tokens": 0 }, "output_tokens": 0, @@ -26116,6 +29077,14 @@ puts(compacted_response) - `:apply_patch` + - `allowed_callers: Array[:direct | :programmatic]` + + The tool invocation context(s). + + - `:direct` + + - `:programmatic` + ### Compacted Response - `class CompactedResponse` @@ -26422,6 +29391,26 @@ puts(compacted_response) The unique ID of the function tool call. + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + - `:program` + - `namespace: String` The namespace of the function to run. @@ -26474,6 +29463,16 @@ puts(compacted_response) - `:input_text` + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + + 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`. + + - `:explicit` + - `class ResponseInputImage` An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). @@ -26504,6 +29503,16 @@ puts(compacted_response) The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + + 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`. + + - `:explicit` + - `class ResponseInputFile` A file input to the model. @@ -26514,9 +29523,11 @@ puts(compacted_response) - `:input_file` - - `detail: :low | :high` + - `detail: :auto | :low | :high` - The detail level of the file to be sent to the model. Use `low` for the default rendering behavior, or `high` to render the file at higher quality. Defaults to `low`. + The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. + + - `:auto` - `:low` @@ -26538,6 +29549,16 @@ puts(compacted_response) The name of the file to be sent to the model. + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + + 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`. + + - `:explicit` + - `status: :in_progress | :completed | :incomplete` The status of the item. One of `in_progress`, `completed`, or @@ -26555,6 +29576,30 @@ puts(compacted_response) - `:function_call_output` + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + The caller type. Always `direct`. + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + The caller type. Always `program`. + + - `:program` + - `created_by: String` The identifier of the actor that created the item. @@ -27222,6 +30267,58 @@ puts(compacted_response) - `:incomplete` + - `class Program` + + - `id: String` + + The unique ID of the program item. + + - `call_id: String` + + The stable call ID of the program item. + + - `code: String` + + The JavaScript source executed by programmatic tool calling. + + - `fingerprint: String` + + Opaque program replay fingerprint that must be round-tripped. + + - `type: :program` + + The type of the item. Always `program`. + + - `:program` + + - `class ProgramOutput` + + - `id: String` + + The unique ID of the program output item. + + - `call_id: String` + + The call ID of the program item. + + - `result: String` + + The result produced by the program item. + + - `status: :completed | :incomplete` + + The terminal status of the program output item. + + - `:completed` + + - `:incomplete` + + - `type: :program_output` + + The type of the item. Always `program_output`. + + - `:program_output` + - `class ResponseToolSearchCall` - `id: String` @@ -27310,7 +30407,7 @@ puts(compacted_response) - `strict: bool` - Whether to enforce strict parameter validation. Default `true`. + Whether strict parameter validation is enforced for this function tool. - `type: :function` @@ -27318,6 +30415,14 @@ puts(compacted_response) - `:function` + - `allowed_callers: Array[:direct | :programmatic]` + + The tool invocation context(s). + + - `:direct` + + - `:programmatic` + - `defer_loading: bool` Whether this function is deferred and loaded via tool search. @@ -27326,6 +30431,10 @@ puts(compacted_response) A description of the function. Used by the model to determine whether or not to call the function. + - `output_schema: Hash[Symbol, untyped]` + + A JSON schema object describing the JSON value encoded in string outputs for this function. + - `class FileSearchTool` A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). @@ -27381,7 +30490,7 @@ puts(compacted_response) - `:nin` - - `value: String | Float | bool | Array[String | Float]` + - `value: String | Float | bool | Array[untyped]` The value to compare against the attribute key; supports string, number, or boolean types. @@ -27391,11 +30500,7 @@ puts(compacted_response) - `UnionMember2 = bool` - - `UnionMember3 = Array[String | Float]` - - - `String = String` - - - `Float = Float` + - `UnionMember3 = Array[untyped]` - `class CompoundFilter` @@ -27568,6 +30673,14 @@ puts(compacted_response) - `:mcp` + - `allowed_callers: Array[:direct | :programmatic]` + + The tool invocation context(s). + + - `:direct` + + - `:programmatic` + - `allowed_tools: Array[String] | McpToolFilter{ read_only, tool_names}` List of allowed tool names or a filter object. @@ -27786,6 +30899,22 @@ puts(compacted_response) - `:code_interpreter` + - `allowed_callers: Array[:direct | :programmatic]` + + The tool invocation context(s). + + - `:direct` + + - `:programmatic` + + - `class ProgrammaticToolCalling` + + - `type: :programmatic_tool_calling` + + The type of the tool. Always `programmatic_tool_calling`. + + - `:programmatic_tool_calling` + - `class ImageGeneration` A tool that generates images using the GPT image models. @@ -27949,6 +31078,14 @@ puts(compacted_response) - `:shell` + - `allowed_callers: Array[:direct | :programmatic]` + + The tool invocation context(s). + + - `:direct` + + - `:programmatic` + - `environment: ContainerAuto | LocalEnvironment | ContainerReference` - `class ContainerAuto` @@ -28089,6 +31226,14 @@ puts(compacted_response) - `:custom` + - `allowed_callers: Array[:direct | :programmatic]` + + The tool invocation context(s). + + - `:direct` + + - `:programmatic` + - `defer_loading: bool` Whether this tool should be deferred and discovered via tool search. @@ -28145,7 +31290,7 @@ puts(compacted_response) The namespace name used in tool calls (for example, `crm`). - - `tools: Array[Function{ name, type, defer_loading, 3 more} | CustomTool]` + - `tools: Array[Function{ name, type, allowed_callers, 5 more} | CustomTool]` The function/custom tools available inside this namespace. @@ -28157,16 +31302,30 @@ puts(compacted_response) - `:function` + - `allowed_callers: Array[:direct | :programmatic]` + + The tool invocation context(s). + + - `:direct` + + - `:programmatic` + - `defer_loading: bool` Whether this function should be deferred and discovered via tool search. - `description: String` + - `output_schema: Hash[Symbol, untyped]` + + A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. + - `parameters: untyped` - `strict: bool` + Whether to enforce strict parameter validation. If omitted, Responses attempts to use strict validation when the schema is compatible, and falls back to non-strict validation otherwise. + - `class CustomTool` A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) @@ -28267,6 +31426,14 @@ puts(compacted_response) - `:apply_patch` + - `allowed_callers: Array[:direct | :programmatic]` + + The tool invocation context(s). + + - `:direct` + + - `:programmatic` + - `type: :tool_search_output` The type of the item. Always `tool_search_output`. @@ -28337,6 +31504,8 @@ puts(compacted_response) A tool that runs Python code to help generate a response to a prompt. + - `class ProgrammaticToolCalling` + - `class ImageGeneration` A tool that generates images using the GPT image models. @@ -28650,6 +31819,26 @@ puts(compacted_response) - `:shell_call` + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + - `:program` + - `created_by: String` The ID of the entity that created this tool call. @@ -28730,6 +31919,26 @@ puts(compacted_response) - `:shell_call_output` + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + - `:program` + - `created_by: String` The identifier of the actor that created the item. @@ -28814,6 +32023,26 @@ puts(compacted_response) - `:apply_patch_call` + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + - `:program` + - `created_by: String` The ID of the entity that created this tool call. @@ -28844,6 +32073,26 @@ puts(compacted_response) - `:apply_patch_call_output` + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + - `:program` + - `created_by: String` The ID of the entity that created this tool call output. @@ -29025,6 +32274,26 @@ puts(compacted_response) The unique ID of the custom tool call in the OpenAI platform. + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + - `:program` + - `namespace: String` The namespace of the custom tool being called. @@ -29060,10 +32329,14 @@ puts(compacted_response) The number of input tokens. - - `input_tokens_details: InputTokensDetails{ cached_tokens}` + - `input_tokens_details: InputTokensDetails{ cache_write_tokens, cached_tokens}` A detailed breakdown of the input tokens. + - `cache_write_tokens: Integer` + + The number of input tokens that were written to the cache. + - `cached_tokens: Integer` The number of tokens that were retrieved from the cache. @@ -29734,6 +33007,14 @@ puts(compacted_response) - `:custom` + - `allowed_callers: Array[:direct | :programmatic]` + + The tool invocation context(s). + + - `:direct` + + - `:programmatic` + - `defer_loading: bool` Whether this tool should be deferred and discovered via tool search. @@ -29816,6 +33097,16 @@ puts(compacted_response) - `:input_text` + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + + 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`. + + - `:explicit` + - `class ResponseInputImage` An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). @@ -29846,6 +33137,16 @@ puts(compacted_response) The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + + 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`. + + - `:explicit` + - `class ResponseInputFile` A file input to the model. @@ -29856,9 +33157,11 @@ puts(compacted_response) - `:input_file` - - `detail: :low | :high` + - `detail: :auto | :low | :high` + + The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. - The detail level of the file to be sent to the model. Use `low` for the default rendering behavior, or `high` to render the file at higher quality. Defaults to `low`. + - `:auto` - `:low` @@ -29880,6 +33183,16 @@ puts(compacted_response) The name of the file to be sent to the model. + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + + 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`. + + - `:explicit` + - `role: :user | :assistant | :system | :developer` The role of the message input. One of `user`, `assistant`, `system`, or @@ -29966,7 +33279,7 @@ puts(compacted_response) - `:nin` - - `value: String | Float | bool | Array[String | Float]` + - `value: String | Float | bool | Array[untyped]` The value to compare against the attribute key; supports string, number, or boolean types. @@ -29976,11 +33289,7 @@ puts(compacted_response) - `UnionMember2 = bool` - - `UnionMember3 = Array[String | Float]` - - - `String = String` - - - `Float = Float` + - `UnionMember3 = Array[untyped]` - `class CompoundFilter` @@ -30048,6 +33357,14 @@ puts(compacted_response) - `:shell` + - `allowed_callers: Array[:direct | :programmatic]` + + The tool invocation context(s). + + - `:direct` + + - `:programmatic` + - `environment: ContainerAuto | LocalEnvironment | ContainerReference` - `class ContainerAuto` @@ -30222,7 +33539,7 @@ puts(compacted_response) - `strict: bool` - Whether to enforce strict parameter validation. Default `true`. + Whether strict parameter validation is enforced for this function tool. - `type: :function` @@ -30230,6 +33547,14 @@ puts(compacted_response) - `:function` + - `allowed_callers: Array[:direct | :programmatic]` + + The tool invocation context(s). + + - `:direct` + + - `:programmatic` + - `defer_loading: bool` Whether this function is deferred and loaded via tool search. @@ -30238,6 +33563,10 @@ puts(compacted_response) A description of the function. Used by the model to determine whether or not to call the function. + - `output_schema: Hash[Symbol, untyped]` + + A JSON schema object describing the JSON value encoded in string outputs for this function. + ### Inline Skill - `class InlineSkill` @@ -30354,7 +33683,7 @@ puts(compacted_response) The namespace name used in tool calls (for example, `crm`). - - `tools: Array[Function{ name, type, defer_loading, 3 more} | CustomTool]` + - `tools: Array[Function{ name, type, allowed_callers, 5 more} | CustomTool]` The function/custom tools available inside this namespace. @@ -30366,16 +33695,30 @@ puts(compacted_response) - `:function` + - `allowed_callers: Array[:direct | :programmatic]` + + The tool invocation context(s). + + - `:direct` + + - `:programmatic` + - `defer_loading: bool` Whether this function should be deferred and discovered via tool search. - `description: String` + - `output_schema: Hash[Symbol, untyped]` + + A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. + - `parameters: untyped` - `strict: bool` + Whether to enforce strict parameter validation. If omitted, Responses attempts to use strict validation when the schema is compatible, and falls back to non-strict validation otherwise. + - `class CustomTool` A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) @@ -30390,6 +33733,14 @@ puts(compacted_response) - `:custom` + - `allowed_callers: Array[:direct | :programmatic]` + + The tool invocation context(s). + + - `:direct` + + - `:programmatic` + - `defer_loading: bool` Whether this tool should be deferred and discovered via tool search. @@ -30456,7 +33807,7 @@ puts(compacted_response) An error object returned when the model fails to generate a Response. - - `code: :server_error | :rate_limit_exceeded | :invalid_prompt | 15 more` + - `code: :server_error | :rate_limit_exceeded | :invalid_prompt | 16 more` The error code for the response. @@ -30466,6 +33817,8 @@ puts(compacted_response) - `:invalid_prompt` + - `:bio_policy` + - `:vector_store_timeout` - `:invalid_image` @@ -30566,6 +33919,16 @@ puts(compacted_response) - `:input_text` + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + + 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`. + + - `:explicit` + - `class ResponseInputImage` An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). @@ -30596,6 +33959,16 @@ puts(compacted_response) The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + + 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`. + + - `:explicit` + - `class ResponseInputFile` A file input to the model. @@ -30606,9 +33979,11 @@ puts(compacted_response) - `:input_file` - - `detail: :low | :high` + - `detail: :auto | :low | :high` - The detail level of the file to be sent to the model. Use `low` for the default rendering behavior, or `high` to render the file at higher quality. Defaults to `low`. + The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. + + - `:auto` - `:low` @@ -30630,6 +34005,16 @@ puts(compacted_response) The name of the file to be sent to the model. + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + + 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`. + + - `:explicit` + - `role: :user | :assistant | :system | :developer` The role of the message input. One of `user`, `assistant`, `system`, or @@ -31577,6 +34962,26 @@ puts(compacted_response) The unique ID of the function tool call. + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + - `:program` + - `namespace: String` The namespace of the function to run. @@ -31626,6 +35031,16 @@ puts(compacted_response) - `:input_text` + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + + 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`. + + - `:explicit` + - `class ResponseInputImageContent` An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) @@ -31656,6 +35071,16 @@ puts(compacted_response) The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + + 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`. + + - `:explicit` + - `class ResponseInputFileContent` A file input to the model. @@ -31666,9 +35091,11 @@ puts(compacted_response) - `:input_file` - - `detail: :low | :high` + - `detail: :auto | :low | :high` - The detail level of the file to be sent to the model. Use `low` for the default rendering behavior, or `high` to render the file at higher quality. Defaults to `low`. + The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. + + - `:auto` - `:low` @@ -31690,6 +35117,16 @@ puts(compacted_response) The name of the file to be sent to the model. + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + + 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`. + + - `:explicit` + - `type: :function_call_output` The type of the function tool call output. Always `function_call_output`. @@ -31700,6 +35137,30 @@ puts(compacted_response) The unique ID of the function tool call output. Populated when this item is returned via API. + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + The caller type. Always `direct`. + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + The caller type. Always `program`. + + - `:program` + - `status: :in_progress | :completed | :incomplete` The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. @@ -31768,7 +35229,7 @@ puts(compacted_response) - `strict: bool` - Whether to enforce strict parameter validation. Default `true`. + Whether strict parameter validation is enforced for this function tool. - `type: :function` @@ -31776,6 +35237,14 @@ puts(compacted_response) - `:function` + - `allowed_callers: Array[:direct | :programmatic]` + + The tool invocation context(s). + + - `:direct` + + - `:programmatic` + - `defer_loading: bool` Whether this function is deferred and loaded via tool search. @@ -31784,6 +35253,10 @@ puts(compacted_response) A description of the function. Used by the model to determine whether or not to call the function. + - `output_schema: Hash[Symbol, untyped]` + + A JSON schema object describing the JSON value encoded in string outputs for this function. + - `class FileSearchTool` A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). @@ -31839,7 +35312,7 @@ puts(compacted_response) - `:nin` - - `value: String | Float | bool | Array[String | Float]` + - `value: String | Float | bool | Array[untyped]` The value to compare against the attribute key; supports string, number, or boolean types. @@ -31849,11 +35322,7 @@ puts(compacted_response) - `UnionMember2 = bool` - - `UnionMember3 = Array[String | Float]` - - - `String = String` - - - `Float = Float` + - `UnionMember3 = Array[untyped]` - `class CompoundFilter` @@ -32026,6 +35495,14 @@ puts(compacted_response) - `:mcp` + - `allowed_callers: Array[:direct | :programmatic]` + + The tool invocation context(s). + + - `:direct` + + - `:programmatic` + - `allowed_tools: Array[String] | McpToolFilter{ read_only, tool_names}` List of allowed tool names or a filter object. @@ -32244,6 +35721,22 @@ puts(compacted_response) - `:code_interpreter` + - `allowed_callers: Array[:direct | :programmatic]` + + The tool invocation context(s). + + - `:direct` + + - `:programmatic` + + - `class ProgrammaticToolCalling` + + - `type: :programmatic_tool_calling` + + The type of the tool. Always `programmatic_tool_calling`. + + - `:programmatic_tool_calling` + - `class ImageGeneration` A tool that generates images using the GPT image models. @@ -32407,6 +35900,14 @@ puts(compacted_response) - `:shell` + - `allowed_callers: Array[:direct | :programmatic]` + + The tool invocation context(s). + + - `:direct` + + - `:programmatic` + - `environment: ContainerAuto | LocalEnvironment | ContainerReference` - `class ContainerAuto` @@ -32547,6 +36048,14 @@ puts(compacted_response) - `:custom` + - `allowed_callers: Array[:direct | :programmatic]` + + The tool invocation context(s). + + - `:direct` + + - `:programmatic` + - `defer_loading: bool` Whether this tool should be deferred and discovered via tool search. @@ -32603,7 +36112,7 @@ puts(compacted_response) The namespace name used in tool calls (for example, `crm`). - - `tools: Array[Function{ name, type, defer_loading, 3 more} | CustomTool]` + - `tools: Array[Function{ name, type, allowed_callers, 5 more} | CustomTool]` The function/custom tools available inside this namespace. @@ -32615,16 +36124,30 @@ puts(compacted_response) - `:function` + - `allowed_callers: Array[:direct | :programmatic]` + + The tool invocation context(s). + + - `:direct` + + - `:programmatic` + - `defer_loading: bool` Whether this function should be deferred and discovered via tool search. - `description: String` + - `output_schema: Hash[Symbol, untyped]` + + A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. + - `parameters: untyped` - `strict: bool` + Whether to enforce strict parameter validation. If omitted, Responses attempts to use strict validation when the schema is compatible, and falls back to non-strict validation otherwise. + - `class CustomTool` A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) @@ -32725,6 +36248,14 @@ puts(compacted_response) - `:apply_patch` + - `allowed_callers: Array[:direct | :programmatic]` + + The tool invocation context(s). + + - `:direct` + + - `:programmatic` + - `type: :tool_search_output` The item type. Always `tool_search_output`. @@ -32799,6 +36330,8 @@ puts(compacted_response) A tool that runs Python code to help generate a response to a prompt. + - `class ProgrammaticToolCalling` + - `class ImageGeneration` A tool that generates images using the GPT image models. @@ -33139,6 +36672,30 @@ puts(compacted_response) The unique ID of the shell tool call. Populated when this item is returned via API. + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + The caller type. Always `direct`. + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + The caller type. Always `program`. + + - `:program` + - `environment: LocalEnvironment | ContainerReference` The environment to execute the shell commands in. @@ -33215,6 +36772,30 @@ puts(compacted_response) The unique ID of the shell tool call output. Populated when this item is returned via API. + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + The caller type. Always `direct`. + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + The caller type. Always `program`. + + - `:program` + - `max_output_length: Integer` The maximum number of UTF-8 characters captured for this shell call's combined output. @@ -33309,6 +36890,30 @@ puts(compacted_response) The unique ID of the apply patch tool call. Populated when this item is returned via API. + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + The caller type. Always `direct`. + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + The caller type. Always `program`. + + - `:program` + - `class ApplyPatchCallOutput` The streamed output emitted by an apply patch tool call. @@ -33335,6 +36940,30 @@ puts(compacted_response) The unique ID of the apply patch tool call output. Populated when this item is returned via API. + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + The caller type. Always `direct`. + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + The caller type. Always `program`. + + - `:program` + - `output: String` Optional human-readable log text from the apply patch tool (e.g., patch results or errors). @@ -33529,6 +37158,30 @@ puts(compacted_response) The unique ID of the custom tool call output in the OpenAI platform. + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + The caller type. Always `direct`. + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + The caller type. Always `program`. + + - `:program` + - `class ResponseCustomToolCall` A call to a custom tool created by the model. @@ -33555,6 +37208,26 @@ puts(compacted_response) The unique ID of the custom tool call in the OpenAI platform. + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + - `:program` + - `namespace: String` The namespace of the custom tool being called. @@ -33583,6 +37256,58 @@ puts(compacted_response) - `:item_reference` + - `class Program` + + - `id: String` + + The unique ID of this program item. + + - `call_id: String` + + The stable call ID of the program item. + + - `code: String` + + The JavaScript source executed by programmatic tool calling. + + - `fingerprint: String` + + Opaque program replay fingerprint that must be round-tripped. + + - `type: :program` + + The item type. Always `program`. + + - `:program` + + - `class ProgramOutput` + + - `id: String` + + The unique ID of this program output item. + + - `call_id: String` + + The call ID of the program item. + + - `result: String` + + The result produced by the program item. + + - `status: :completed | :incomplete` + + The terminal status of the program output. + + - `:completed` + + - `:incomplete` + + - `type: :program_output` + + The item type. Always `program_output`. + + - `:program_output` + - `metadata: Metadata` Set of 16 key-value pairs that can be attached to an object. This can be @@ -33601,7 +37326,13 @@ puts(compacted_response) - `String = String` - - `ChatModel = :"gpt-5.4" | :"gpt-5.4-mini" | :"gpt-5.4-nano" | 75 more` + - `ChatModel = :"gpt-5.6-sol" | :"gpt-5.6-terra" | :"gpt-5.6-luna" | 78 more` + + - `:"gpt-5.6-sol"` + + - `:"gpt-5.6-terra"` + + - `:"gpt-5.6-luna"` - `:"gpt-5.4"` @@ -33872,6 +37603,30 @@ puts(compacted_response) - `:function_call_output` + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + The caller type. Always `direct`. + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + The caller type. Always `program`. + + - `:program` + - `created_by: String` The identifier of the actor that created the item. @@ -33947,6 +37702,58 @@ puts(compacted_response) for subsequent turns of a conversation if you are manually [managing context](https://platform.openai.com/docs/guides/conversation-state). + - `class Program` + + - `id: String` + + The unique ID of the program item. + + - `call_id: String` + + The stable call ID of the program item. + + - `code: String` + + The JavaScript source executed by programmatic tool calling. + + - `fingerprint: String` + + Opaque program replay fingerprint that must be round-tripped. + + - `type: :program` + + The type of the item. Always `program`. + + - `:program` + + - `class ProgramOutput` + + - `id: String` + + The unique ID of the program output item. + + - `call_id: String` + + The call ID of the program item. + + - `result: String` + + The result produced by the program item. + + - `status: :completed | :incomplete` + + The terminal status of the program output item. + + - `:completed` + + - `:incomplete` + + - `type: :program_output` + + The type of the item. Always `program_output`. + + - `:program_output` + - `class ResponseToolSearchCall` - `id: String` @@ -34051,6 +37858,8 @@ puts(compacted_response) A tool that runs Python code to help generate a response to a prompt. + - `class ProgrammaticToolCalling` + - `class ImageGeneration` A tool that generates images using the GPT image models. @@ -34153,6 +37962,8 @@ puts(compacted_response) A tool that runs Python code to help generate a response to a prompt. + - `class ProgrammaticToolCalling` + - `class ImageGeneration` A tool that generates images using the GPT image models. @@ -34401,6 +38212,26 @@ puts(compacted_response) - `:shell_call` + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + - `:program` + - `created_by: String` The ID of the entity that created this tool call. @@ -34481,6 +38312,26 @@ puts(compacted_response) - `:shell_call_output` + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + - `:program` + - `created_by: String` The identifier of the actor that created the item. @@ -34565,6 +38416,26 @@ puts(compacted_response) - `:apply_patch_call` + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + - `:program` + - `created_by: String` The ID of the entity that created this tool call. @@ -34595,6 +38466,26 @@ puts(compacted_response) - `:apply_patch_call_output` + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + - `:program` + - `created_by: String` The ID of the entity that created this tool call output. @@ -34786,7 +38677,7 @@ puts(compacted_response) What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. We generally recommend altering this or `top_p` but not both. - - `tool_choice: ToolChoiceOptions | ToolChoiceAllowed | ToolChoiceTypes | 5 more` + - `tool_choice: ToolChoiceOptions | ToolChoiceAllowed | ToolChoiceTypes | 6 more` How the model should select which tool (or tools) to use when generating a response. See the `tools` parameter to see how to specify which tools @@ -34928,6 +38819,14 @@ puts(compacted_response) - `:custom` + - `class SpecificProgrammaticToolCallingParam` + + - `type: :programmatic_tool_calling` + + The tool to call. Always `programmatic_tool_calling`. + + - `:programmatic_tool_calling` + - `class ToolChoiceApplyPatch` Forces the model to call the apply_patch tool when executing a tool call. @@ -34998,6 +38897,8 @@ puts(compacted_response) A tool that runs Python code to help generate a response to a prompt. + - `class ProgrammaticToolCalling` + - `class ImageGeneration` A tool that generates images using the GPT image models. @@ -35224,9 +39125,32 @@ puts(compacted_response) Used by OpenAI to cache responses for similar requests to optimize your cache hit rates. Replaces the `user` field. [Learn more](https://platform.openai.com/docs/guides/prompt-caching). + - `prompt_cache_options: PromptCacheOptions{ mode, ttl}` + + The prompt-caching options that were applied to the response. Supported for `gpt-5.6` and later models. + + - `mode: :implicit | :explicit` + + Whether implicit prompt-cache breakpoints were enabled. + + - `:implicit` + + - `:explicit` + + - `ttl: :"30m"` + + The minimum lifetime applied to each cache breakpoint. + + - `:"30m"` + - `prompt_cache_retention: :in_memory | :"24h"` + Deprecated. Use `prompt_cache_options.ttl` instead. + The retention policy for the prompt cache. Set to `24h` to enable extended prompt caching, which keeps cached prefixes active for longer, up to a maximum of 24 hours. [Learn more](https://platform.openai.com/docs/guides/prompt-caching#prompt-cache-retention). + This field expresses a maximum retention policy, while + `prompt_cache_options.ttl` expresses a minimum cache lifetime. The two + fields are independent and do not interact. For `gpt-5.5`, `gpt-5.5-pro`, and future models, only `24h` is supported. For older models that support both `in_memory` and `24h`, the default depends on your organization's data retention policy: @@ -35259,16 +39183,13 @@ puts(compacted_response) - `effort: ReasoningEffort` - Constrains effort on reasoning for - [reasoning models](https://platform.openai.com/docs/guides/reasoning). - Currently supported values are `none`, `minimal`, `low`, `medium`, `high`, and `xhigh`. Reducing - reasoning effort can result in faster responses and fewer tokens used - on reasoning in a response. - - - `gpt-5.1` defaults to `none`, which does not perform reasoning. The supported reasoning values for `gpt-5.1` are `none`, `low`, `medium`, and `high`. Tool calls are supported for all reasoning values in gpt-5.1. - - All models before `gpt-5.1` default to `medium` reasoning effort, and do not support `none`. - - The `gpt-5-pro` model defaults to (and only supports) `high` reasoning effort. - - `xhigh` is supported for all models after `gpt-5.1-codex-max`. + Constrains effort on reasoning for reasoning models. Currently supported + values are `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max`. + Reducing reasoning effort can result in faster responses and fewer tokens + used on reasoning in a response. Not all reasoning models support every + value. See the + [reasoning guide](https://platform.openai.com/docs/guides/reasoning) + for model-specific support. - `:none` @@ -35282,6 +39203,8 @@ puts(compacted_response) - `:xhigh` + - `:max` + - `generate_summary: :auto | :concise | :detailed` **Deprecated:** use `summary` instead. @@ -35296,6 +39219,24 @@ puts(compacted_response) - `:detailed` + - `mode: String | :standard | :pro` + + Controls the reasoning execution mode for the request. + + When returned on a response, this is the effective execution mode. + + - `String = String` + + - `Mode = :standard | :pro` + + Controls the reasoning execution mode for the request. + + When returned on a response, this is the effective execution mode. + + - `:standard` + + - `:pro` + - `summary: :auto | :concise | :detailed` A summary of the reasoning performed by the model. This can be @@ -35476,10 +39417,14 @@ puts(compacted_response) The number of input tokens. - - `input_tokens_details: InputTokensDetails{ cached_tokens}` + - `input_tokens_details: InputTokensDetails{ cache_write_tokens, cached_tokens}` A detailed breakdown of the input tokens. + - `cache_write_tokens: Integer` + + The number of input tokens that were written to the cache. + - `cached_tokens: Integer` The number of tokens that were retrieved from the cache. @@ -35589,6 +39534,26 @@ puts(compacted_response) - `:apply_patch_call` + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + - `:program` + - `created_by: String` The ID of the entity that created this tool call. @@ -35621,6 +39586,26 @@ puts(compacted_response) - `:apply_patch_call_output` + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + - `:program` + - `created_by: String` The ID of the entity that created this tool call output. @@ -35966,7 +39951,7 @@ puts(compacted_response) An error object returned when the model fails to generate a Response. - - `code: :server_error | :rate_limit_exceeded | :invalid_prompt | 15 more` + - `code: :server_error | :rate_limit_exceeded | :invalid_prompt | 16 more` The error code for the response. @@ -35976,6 +39961,8 @@ puts(compacted_response) - `:invalid_prompt` + - `:bio_policy` + - `:vector_store_timeout` - `:invalid_image` @@ -36076,6 +40063,16 @@ puts(compacted_response) - `:input_text` + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + + 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`. + + - `:explicit` + - `class ResponseInputImage` An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). @@ -36106,6 +40103,16 @@ puts(compacted_response) The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + + 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`. + + - `:explicit` + - `class ResponseInputFile` A file input to the model. @@ -36116,9 +40123,11 @@ puts(compacted_response) - `:input_file` - - `detail: :low | :high` + - `detail: :auto | :low | :high` - The detail level of the file to be sent to the model. Use `low` for the default rendering behavior, or `high` to render the file at higher quality. Defaults to `low`. + The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. + + - `:auto` - `:low` @@ -36140,6 +40149,16 @@ puts(compacted_response) The name of the file to be sent to the model. + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + + 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`. + + - `:explicit` + - `role: :user | :assistant | :system | :developer` The role of the message input. One of `user`, `assistant`, `system`, or @@ -37087,6 +41106,26 @@ puts(compacted_response) The unique ID of the function tool call. + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + - `:program` + - `namespace: String` The namespace of the function to run. @@ -37136,6 +41175,16 @@ puts(compacted_response) - `:input_text` + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + + 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`. + + - `:explicit` + - `class ResponseInputImageContent` An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) @@ -37166,6 +41215,16 @@ puts(compacted_response) The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + + 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`. + + - `:explicit` + - `class ResponseInputFileContent` A file input to the model. @@ -37176,9 +41235,11 @@ puts(compacted_response) - `:input_file` - - `detail: :low | :high` + - `detail: :auto | :low | :high` - The detail level of the file to be sent to the model. Use `low` for the default rendering behavior, or `high` to render the file at higher quality. Defaults to `low`. + The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. + + - `:auto` - `:low` @@ -37200,6 +41261,16 @@ puts(compacted_response) The name of the file to be sent to the model. + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + + 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`. + + - `:explicit` + - `type: :function_call_output` The type of the function tool call output. Always `function_call_output`. @@ -37210,6 +41281,30 @@ puts(compacted_response) The unique ID of the function tool call output. Populated when this item is returned via API. + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + The caller type. Always `direct`. + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + The caller type. Always `program`. + + - `:program` + - `status: :in_progress | :completed | :incomplete` The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. @@ -37278,7 +41373,7 @@ puts(compacted_response) - `strict: bool` - Whether to enforce strict parameter validation. Default `true`. + Whether strict parameter validation is enforced for this function tool. - `type: :function` @@ -37286,6 +41381,14 @@ puts(compacted_response) - `:function` + - `allowed_callers: Array[:direct | :programmatic]` + + The tool invocation context(s). + + - `:direct` + + - `:programmatic` + - `defer_loading: bool` Whether this function is deferred and loaded via tool search. @@ -37294,6 +41397,10 @@ puts(compacted_response) A description of the function. Used by the model to determine whether or not to call the function. + - `output_schema: Hash[Symbol, untyped]` + + A JSON schema object describing the JSON value encoded in string outputs for this function. + - `class FileSearchTool` A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). @@ -37349,7 +41456,7 @@ puts(compacted_response) - `:nin` - - `value: String | Float | bool | Array[String | Float]` + - `value: String | Float | bool | Array[untyped]` The value to compare against the attribute key; supports string, number, or boolean types. @@ -37359,11 +41466,7 @@ puts(compacted_response) - `UnionMember2 = bool` - - `UnionMember3 = Array[String | Float]` - - - `String = String` - - - `Float = Float` + - `UnionMember3 = Array[untyped]` - `class CompoundFilter` @@ -37536,6 +41639,14 @@ puts(compacted_response) - `:mcp` + - `allowed_callers: Array[:direct | :programmatic]` + + The tool invocation context(s). + + - `:direct` + + - `:programmatic` + - `allowed_tools: Array[String] | McpToolFilter{ read_only, tool_names}` List of allowed tool names or a filter object. @@ -37754,6 +41865,22 @@ puts(compacted_response) - `:code_interpreter` + - `allowed_callers: Array[:direct | :programmatic]` + + The tool invocation context(s). + + - `:direct` + + - `:programmatic` + + - `class ProgrammaticToolCalling` + + - `type: :programmatic_tool_calling` + + The type of the tool. Always `programmatic_tool_calling`. + + - `:programmatic_tool_calling` + - `class ImageGeneration` A tool that generates images using the GPT image models. @@ -37917,6 +42044,14 @@ puts(compacted_response) - `:shell` + - `allowed_callers: Array[:direct | :programmatic]` + + The tool invocation context(s). + + - `:direct` + + - `:programmatic` + - `environment: ContainerAuto | LocalEnvironment | ContainerReference` - `class ContainerAuto` @@ -38057,6 +42192,14 @@ puts(compacted_response) - `:custom` + - `allowed_callers: Array[:direct | :programmatic]` + + The tool invocation context(s). + + - `:direct` + + - `:programmatic` + - `defer_loading: bool` Whether this tool should be deferred and discovered via tool search. @@ -38113,7 +42256,7 @@ puts(compacted_response) The namespace name used in tool calls (for example, `crm`). - - `tools: Array[Function{ name, type, defer_loading, 3 more} | CustomTool]` + - `tools: Array[Function{ name, type, allowed_callers, 5 more} | CustomTool]` The function/custom tools available inside this namespace. @@ -38125,16 +42268,30 @@ puts(compacted_response) - `:function` + - `allowed_callers: Array[:direct | :programmatic]` + + The tool invocation context(s). + + - `:direct` + + - `:programmatic` + - `defer_loading: bool` Whether this function should be deferred and discovered via tool search. - `description: String` + - `output_schema: Hash[Symbol, untyped]` + + A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. + - `parameters: untyped` - `strict: bool` + Whether to enforce strict parameter validation. If omitted, Responses attempts to use strict validation when the schema is compatible, and falls back to non-strict validation otherwise. + - `class CustomTool` A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) @@ -38235,6 +42392,14 @@ puts(compacted_response) - `:apply_patch` + - `allowed_callers: Array[:direct | :programmatic]` + + The tool invocation context(s). + + - `:direct` + + - `:programmatic` + - `type: :tool_search_output` The item type. Always `tool_search_output`. @@ -38309,6 +42474,8 @@ puts(compacted_response) A tool that runs Python code to help generate a response to a prompt. + - `class ProgrammaticToolCalling` + - `class ImageGeneration` A tool that generates images using the GPT image models. @@ -38649,6 +42816,30 @@ puts(compacted_response) The unique ID of the shell tool call. Populated when this item is returned via API. + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + The caller type. Always `direct`. + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + The caller type. Always `program`. + + - `:program` + - `environment: LocalEnvironment | ContainerReference` The environment to execute the shell commands in. @@ -38725,6 +42916,30 @@ puts(compacted_response) The unique ID of the shell tool call output. Populated when this item is returned via API. + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + The caller type. Always `direct`. + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + The caller type. Always `program`. + + - `:program` + - `max_output_length: Integer` The maximum number of UTF-8 characters captured for this shell call's combined output. @@ -38819,6 +43034,30 @@ puts(compacted_response) The unique ID of the apply patch tool call. Populated when this item is returned via API. + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + The caller type. Always `direct`. + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + The caller type. Always `program`. + + - `:program` + - `class ApplyPatchCallOutput` The streamed output emitted by an apply patch tool call. @@ -38845,6 +43084,30 @@ puts(compacted_response) The unique ID of the apply patch tool call output. Populated when this item is returned via API. + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + The caller type. Always `direct`. + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + The caller type. Always `program`. + + - `:program` + - `output: String` Optional human-readable log text from the apply patch tool (e.g., patch results or errors). @@ -39039,6 +43302,30 @@ puts(compacted_response) The unique ID of the custom tool call output in the OpenAI platform. + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + The caller type. Always `direct`. + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + The caller type. Always `program`. + + - `:program` + - `class ResponseCustomToolCall` A call to a custom tool created by the model. @@ -39065,6 +43352,26 @@ puts(compacted_response) The unique ID of the custom tool call in the OpenAI platform. + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + - `:program` + - `namespace: String` The namespace of the custom tool being called. @@ -39093,6 +43400,58 @@ puts(compacted_response) - `:item_reference` + - `class Program` + + - `id: String` + + The unique ID of this program item. + + - `call_id: String` + + The stable call ID of the program item. + + - `code: String` + + The JavaScript source executed by programmatic tool calling. + + - `fingerprint: String` + + Opaque program replay fingerprint that must be round-tripped. + + - `type: :program` + + The item type. Always `program`. + + - `:program` + + - `class ProgramOutput` + + - `id: String` + + The unique ID of this program output item. + + - `call_id: String` + + The call ID of the program item. + + - `result: String` + + The result produced by the program item. + + - `status: :completed | :incomplete` + + The terminal status of the program output. + + - `:completed` + + - `:incomplete` + + - `type: :program_output` + + The item type. Always `program_output`. + + - `:program_output` + - `metadata: Metadata` Set of 16 key-value pairs that can be attached to an object. This can be @@ -39111,7 +43470,13 @@ puts(compacted_response) - `String = String` - - `ChatModel = :"gpt-5.4" | :"gpt-5.4-mini" | :"gpt-5.4-nano" | 75 more` + - `ChatModel = :"gpt-5.6-sol" | :"gpt-5.6-terra" | :"gpt-5.6-luna" | 78 more` + + - `:"gpt-5.6-sol"` + + - `:"gpt-5.6-terra"` + + - `:"gpt-5.6-luna"` - `:"gpt-5.4"` @@ -39382,6 +43747,30 @@ puts(compacted_response) - `:function_call_output` + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + The caller type. Always `direct`. + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + The caller type. Always `program`. + + - `:program` + - `created_by: String` The identifier of the actor that created the item. @@ -39457,6 +43846,58 @@ puts(compacted_response) for subsequent turns of a conversation if you are manually [managing context](https://platform.openai.com/docs/guides/conversation-state). + - `class Program` + + - `id: String` + + The unique ID of the program item. + + - `call_id: String` + + The stable call ID of the program item. + + - `code: String` + + The JavaScript source executed by programmatic tool calling. + + - `fingerprint: String` + + Opaque program replay fingerprint that must be round-tripped. + + - `type: :program` + + The type of the item. Always `program`. + + - `:program` + + - `class ProgramOutput` + + - `id: String` + + The unique ID of the program output item. + + - `call_id: String` + + The call ID of the program item. + + - `result: String` + + The result produced by the program item. + + - `status: :completed | :incomplete` + + The terminal status of the program output item. + + - `:completed` + + - `:incomplete` + + - `type: :program_output` + + The type of the item. Always `program_output`. + + - `:program_output` + - `class ResponseToolSearchCall` - `id: String` @@ -39561,6 +44002,8 @@ puts(compacted_response) A tool that runs Python code to help generate a response to a prompt. + - `class ProgrammaticToolCalling` + - `class ImageGeneration` A tool that generates images using the GPT image models. @@ -39663,6 +44106,8 @@ puts(compacted_response) A tool that runs Python code to help generate a response to a prompt. + - `class ProgrammaticToolCalling` + - `class ImageGeneration` A tool that generates images using the GPT image models. @@ -39911,6 +44356,26 @@ puts(compacted_response) - `:shell_call` + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + - `:program` + - `created_by: String` The ID of the entity that created this tool call. @@ -39991,6 +44456,26 @@ puts(compacted_response) - `:shell_call_output` + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + - `:program` + - `created_by: String` The identifier of the actor that created the item. @@ -40075,6 +44560,26 @@ puts(compacted_response) - `:apply_patch_call` + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + - `:program` + - `created_by: String` The ID of the entity that created this tool call. @@ -40105,6 +44610,26 @@ puts(compacted_response) - `:apply_patch_call_output` + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + - `:program` + - `created_by: String` The ID of the entity that created this tool call output. @@ -40296,7 +44821,7 @@ puts(compacted_response) What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. We generally recommend altering this or `top_p` but not both. - - `tool_choice: ToolChoiceOptions | ToolChoiceAllowed | ToolChoiceTypes | 5 more` + - `tool_choice: ToolChoiceOptions | ToolChoiceAllowed | ToolChoiceTypes | 6 more` How the model should select which tool (or tools) to use when generating a response. See the `tools` parameter to see how to specify which tools @@ -40438,6 +44963,14 @@ puts(compacted_response) - `:custom` + - `class SpecificProgrammaticToolCallingParam` + + - `type: :programmatic_tool_calling` + + The tool to call. Always `programmatic_tool_calling`. + + - `:programmatic_tool_calling` + - `class ToolChoiceApplyPatch` Forces the model to call the apply_patch tool when executing a tool call. @@ -40508,6 +45041,8 @@ puts(compacted_response) A tool that runs Python code to help generate a response to a prompt. + - `class ProgrammaticToolCalling` + - `class ImageGeneration` A tool that generates images using the GPT image models. @@ -40734,9 +45269,32 @@ puts(compacted_response) Used by OpenAI to cache responses for similar requests to optimize your cache hit rates. Replaces the `user` field. [Learn more](https://platform.openai.com/docs/guides/prompt-caching). + - `prompt_cache_options: PromptCacheOptions{ mode, ttl}` + + The prompt-caching options that were applied to the response. Supported for `gpt-5.6` and later models. + + - `mode: :implicit | :explicit` + + Whether implicit prompt-cache breakpoints were enabled. + + - `:implicit` + + - `:explicit` + + - `ttl: :"30m"` + + The minimum lifetime applied to each cache breakpoint. + + - `:"30m"` + - `prompt_cache_retention: :in_memory | :"24h"` + Deprecated. Use `prompt_cache_options.ttl` instead. + The retention policy for the prompt cache. Set to `24h` to enable extended prompt caching, which keeps cached prefixes active for longer, up to a maximum of 24 hours. [Learn more](https://platform.openai.com/docs/guides/prompt-caching#prompt-cache-retention). + This field expresses a maximum retention policy, while + `prompt_cache_options.ttl` expresses a minimum cache lifetime. The two + fields are independent and do not interact. For `gpt-5.5`, `gpt-5.5-pro`, and future models, only `24h` is supported. For older models that support both `in_memory` and `24h`, the default depends on your organization's data retention policy: @@ -40769,16 +45327,13 @@ puts(compacted_response) - `effort: ReasoningEffort` - Constrains effort on reasoning for - [reasoning models](https://platform.openai.com/docs/guides/reasoning). - Currently supported values are `none`, `minimal`, `low`, `medium`, `high`, and `xhigh`. Reducing - reasoning effort can result in faster responses and fewer tokens used - on reasoning in a response. - - - `gpt-5.1` defaults to `none`, which does not perform reasoning. The supported reasoning values for `gpt-5.1` are `none`, `low`, `medium`, and `high`. Tool calls are supported for all reasoning values in gpt-5.1. - - All models before `gpt-5.1` default to `medium` reasoning effort, and do not support `none`. - - The `gpt-5-pro` model defaults to (and only supports) `high` reasoning effort. - - `xhigh` is supported for all models after `gpt-5.1-codex-max`. + Constrains effort on reasoning for reasoning models. Currently supported + values are `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max`. + Reducing reasoning effort can result in faster responses and fewer tokens + used on reasoning in a response. Not all reasoning models support every + value. See the + [reasoning guide](https://platform.openai.com/docs/guides/reasoning) + for model-specific support. - `:none` @@ -40792,6 +45347,8 @@ puts(compacted_response) - `:xhigh` + - `:max` + - `generate_summary: :auto | :concise | :detailed` **Deprecated:** use `summary` instead. @@ -40806,6 +45363,24 @@ puts(compacted_response) - `:detailed` + - `mode: String | :standard | :pro` + + Controls the reasoning execution mode for the request. + + When returned on a response, this is the effective execution mode. + + - `String = String` + + - `Mode = :standard | :pro` + + Controls the reasoning execution mode for the request. + + When returned on a response, this is the effective execution mode. + + - `:standard` + + - `:pro` + - `summary: :auto | :concise | :detailed` A summary of the reasoning performed by the model. This can be @@ -40986,10 +45561,14 @@ puts(compacted_response) The number of input tokens. - - `input_tokens_details: InputTokensDetails{ cached_tokens}` + - `input_tokens_details: InputTokensDetails{ cache_write_tokens, cached_tokens}` A detailed breakdown of the input tokens. + - `cache_write_tokens: Integer` + + The number of input tokens that were written to the cache. + - `cached_tokens: Integer` The number of tokens that were retrieved from the cache. @@ -41592,6 +46171,16 @@ puts(compacted_response) - `:input_text` + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + + 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`. + + - `:explicit` + - `class ResponseInputImage` An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). @@ -41622,6 +46211,16 @@ puts(compacted_response) The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + + 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`. + + - `:explicit` + - `class ResponseInputFile` A file input to the model. @@ -41632,9 +46231,11 @@ puts(compacted_response) - `:input_file` - - `detail: :low | :high` + - `detail: :auto | :low | :high` - The detail level of the file to be sent to the model. Use `low` for the default rendering behavior, or `high` to render the file at higher quality. Defaults to `low`. + The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. + + - `:auto` - `:low` @@ -41656,6 +46257,16 @@ puts(compacted_response) The name of the file to be sent to the model. + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + + 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`. + + - `:explicit` + - `class ResponseOutputText` A text output from the model. @@ -42226,7 +46837,7 @@ puts(compacted_response) An error object returned when the model fails to generate a Response. - - `code: :server_error | :rate_limit_exceeded | :invalid_prompt | 15 more` + - `code: :server_error | :rate_limit_exceeded | :invalid_prompt | 16 more` The error code for the response. @@ -42236,6 +46847,8 @@ puts(compacted_response) - `:invalid_prompt` + - `:bio_policy` + - `:vector_store_timeout` - `:invalid_image` @@ -42336,6 +46949,16 @@ puts(compacted_response) - `:input_text` + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + + 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`. + + - `:explicit` + - `class ResponseInputImage` An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). @@ -42366,6 +46989,16 @@ puts(compacted_response) The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + + 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`. + + - `:explicit` + - `class ResponseInputFile` A file input to the model. @@ -42376,9 +47009,11 @@ puts(compacted_response) - `:input_file` - - `detail: :low | :high` + - `detail: :auto | :low | :high` - The detail level of the file to be sent to the model. Use `low` for the default rendering behavior, or `high` to render the file at higher quality. Defaults to `low`. + The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. + + - `:auto` - `:low` @@ -42400,6 +47035,16 @@ puts(compacted_response) The name of the file to be sent to the model. + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + + 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`. + + - `:explicit` + - `role: :user | :assistant | :system | :developer` The role of the message input. One of `user`, `assistant`, `system`, or @@ -43347,6 +47992,26 @@ puts(compacted_response) The unique ID of the function tool call. + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + - `:program` + - `namespace: String` The namespace of the function to run. @@ -43396,6 +48061,16 @@ puts(compacted_response) - `:input_text` + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + + 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`. + + - `:explicit` + - `class ResponseInputImageContent` An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) @@ -43426,6 +48101,16 @@ puts(compacted_response) The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + + 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`. + + - `:explicit` + - `class ResponseInputFileContent` A file input to the model. @@ -43436,9 +48121,11 @@ puts(compacted_response) - `:input_file` - - `detail: :low | :high` + - `detail: :auto | :low | :high` + + The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. - The detail level of the file to be sent to the model. Use `low` for the default rendering behavior, or `high` to render the file at higher quality. Defaults to `low`. + - `:auto` - `:low` @@ -43460,6 +48147,16 @@ puts(compacted_response) The name of the file to be sent to the model. + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + + 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`. + + - `:explicit` + - `type: :function_call_output` The type of the function tool call output. Always `function_call_output`. @@ -43470,6 +48167,30 @@ puts(compacted_response) The unique ID of the function tool call output. Populated when this item is returned via API. + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + The caller type. Always `direct`. + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + The caller type. Always `program`. + + - `:program` + - `status: :in_progress | :completed | :incomplete` The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. @@ -43538,7 +48259,7 @@ puts(compacted_response) - `strict: bool` - Whether to enforce strict parameter validation. Default `true`. + Whether strict parameter validation is enforced for this function tool. - `type: :function` @@ -43546,6 +48267,14 @@ puts(compacted_response) - `:function` + - `allowed_callers: Array[:direct | :programmatic]` + + The tool invocation context(s). + + - `:direct` + + - `:programmatic` + - `defer_loading: bool` Whether this function is deferred and loaded via tool search. @@ -43554,6 +48283,10 @@ puts(compacted_response) A description of the function. Used by the model to determine whether or not to call the function. + - `output_schema: Hash[Symbol, untyped]` + + A JSON schema object describing the JSON value encoded in string outputs for this function. + - `class FileSearchTool` A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). @@ -43609,7 +48342,7 @@ puts(compacted_response) - `:nin` - - `value: String | Float | bool | Array[String | Float]` + - `value: String | Float | bool | Array[untyped]` The value to compare against the attribute key; supports string, number, or boolean types. @@ -43619,11 +48352,7 @@ puts(compacted_response) - `UnionMember2 = bool` - - `UnionMember3 = Array[String | Float]` - - - `String = String` - - - `Float = Float` + - `UnionMember3 = Array[untyped]` - `class CompoundFilter` @@ -43796,6 +48525,14 @@ puts(compacted_response) - `:mcp` + - `allowed_callers: Array[:direct | :programmatic]` + + The tool invocation context(s). + + - `:direct` + + - `:programmatic` + - `allowed_tools: Array[String] | McpToolFilter{ read_only, tool_names}` List of allowed tool names or a filter object. @@ -44014,6 +48751,22 @@ puts(compacted_response) - `:code_interpreter` + - `allowed_callers: Array[:direct | :programmatic]` + + The tool invocation context(s). + + - `:direct` + + - `:programmatic` + + - `class ProgrammaticToolCalling` + + - `type: :programmatic_tool_calling` + + The type of the tool. Always `programmatic_tool_calling`. + + - `:programmatic_tool_calling` + - `class ImageGeneration` A tool that generates images using the GPT image models. @@ -44177,6 +48930,14 @@ puts(compacted_response) - `:shell` + - `allowed_callers: Array[:direct | :programmatic]` + + The tool invocation context(s). + + - `:direct` + + - `:programmatic` + - `environment: ContainerAuto | LocalEnvironment | ContainerReference` - `class ContainerAuto` @@ -44317,6 +49078,14 @@ puts(compacted_response) - `:custom` + - `allowed_callers: Array[:direct | :programmatic]` + + The tool invocation context(s). + + - `:direct` + + - `:programmatic` + - `defer_loading: bool` Whether this tool should be deferred and discovered via tool search. @@ -44373,7 +49142,7 @@ puts(compacted_response) The namespace name used in tool calls (for example, `crm`). - - `tools: Array[Function{ name, type, defer_loading, 3 more} | CustomTool]` + - `tools: Array[Function{ name, type, allowed_callers, 5 more} | CustomTool]` The function/custom tools available inside this namespace. @@ -44385,16 +49154,30 @@ puts(compacted_response) - `:function` + - `allowed_callers: Array[:direct | :programmatic]` + + The tool invocation context(s). + + - `:direct` + + - `:programmatic` + - `defer_loading: bool` Whether this function should be deferred and discovered via tool search. - `description: String` + - `output_schema: Hash[Symbol, untyped]` + + A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. + - `parameters: untyped` - `strict: bool` + Whether to enforce strict parameter validation. If omitted, Responses attempts to use strict validation when the schema is compatible, and falls back to non-strict validation otherwise. + - `class CustomTool` A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) @@ -44495,6 +49278,14 @@ puts(compacted_response) - `:apply_patch` + - `allowed_callers: Array[:direct | :programmatic]` + + The tool invocation context(s). + + - `:direct` + + - `:programmatic` + - `type: :tool_search_output` The item type. Always `tool_search_output`. @@ -44569,6 +49360,8 @@ puts(compacted_response) A tool that runs Python code to help generate a response to a prompt. + - `class ProgrammaticToolCalling` + - `class ImageGeneration` A tool that generates images using the GPT image models. @@ -44909,6 +49702,30 @@ puts(compacted_response) The unique ID of the shell tool call. Populated when this item is returned via API. + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + The caller type. Always `direct`. + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + The caller type. Always `program`. + + - `:program` + - `environment: LocalEnvironment | ContainerReference` The environment to execute the shell commands in. @@ -44985,6 +49802,30 @@ puts(compacted_response) The unique ID of the shell tool call output. Populated when this item is returned via API. + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + The caller type. Always `direct`. + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + The caller type. Always `program`. + + - `:program` + - `max_output_length: Integer` The maximum number of UTF-8 characters captured for this shell call's combined output. @@ -45079,6 +49920,30 @@ puts(compacted_response) The unique ID of the apply patch tool call. Populated when this item is returned via API. + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + The caller type. Always `direct`. + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + The caller type. Always `program`. + + - `:program` + - `class ApplyPatchCallOutput` The streamed output emitted by an apply patch tool call. @@ -45105,6 +49970,30 @@ puts(compacted_response) The unique ID of the apply patch tool call output. Populated when this item is returned via API. + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + The caller type. Always `direct`. + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + The caller type. Always `program`. + + - `:program` + - `output: String` Optional human-readable log text from the apply patch tool (e.g., patch results or errors). @@ -45299,6 +50188,30 @@ puts(compacted_response) The unique ID of the custom tool call output in the OpenAI platform. + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + The caller type. Always `direct`. + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + The caller type. Always `program`. + + - `:program` + - `class ResponseCustomToolCall` A call to a custom tool created by the model. @@ -45325,6 +50238,26 @@ puts(compacted_response) The unique ID of the custom tool call in the OpenAI platform. + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + - `:program` + - `namespace: String` The namespace of the custom tool being called. @@ -45353,6 +50286,58 @@ puts(compacted_response) - `:item_reference` + - `class Program` + + - `id: String` + + The unique ID of this program item. + + - `call_id: String` + + The stable call ID of the program item. + + - `code: String` + + The JavaScript source executed by programmatic tool calling. + + - `fingerprint: String` + + Opaque program replay fingerprint that must be round-tripped. + + - `type: :program` + + The item type. Always `program`. + + - `:program` + + - `class ProgramOutput` + + - `id: String` + + The unique ID of this program output item. + + - `call_id: String` + + The call ID of the program item. + + - `result: String` + + The result produced by the program item. + + - `status: :completed | :incomplete` + + The terminal status of the program output. + + - `:completed` + + - `:incomplete` + + - `type: :program_output` + + The item type. Always `program_output`. + + - `:program_output` + - `metadata: Metadata` Set of 16 key-value pairs that can be attached to an object. This can be @@ -45371,7 +50356,13 @@ puts(compacted_response) - `String = String` - - `ChatModel = :"gpt-5.4" | :"gpt-5.4-mini" | :"gpt-5.4-nano" | 75 more` + - `ChatModel = :"gpt-5.6-sol" | :"gpt-5.6-terra" | :"gpt-5.6-luna" | 78 more` + + - `:"gpt-5.6-sol"` + + - `:"gpt-5.6-terra"` + + - `:"gpt-5.6-luna"` - `:"gpt-5.4"` @@ -45642,6 +50633,30 @@ puts(compacted_response) - `:function_call_output` + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + The caller type. Always `direct`. + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + The caller type. Always `program`. + + - `:program` + - `created_by: String` The identifier of the actor that created the item. @@ -45717,6 +50732,58 @@ puts(compacted_response) for subsequent turns of a conversation if you are manually [managing context](https://platform.openai.com/docs/guides/conversation-state). + - `class Program` + + - `id: String` + + The unique ID of the program item. + + - `call_id: String` + + The stable call ID of the program item. + + - `code: String` + + The JavaScript source executed by programmatic tool calling. + + - `fingerprint: String` + + Opaque program replay fingerprint that must be round-tripped. + + - `type: :program` + + The type of the item. Always `program`. + + - `:program` + + - `class ProgramOutput` + + - `id: String` + + The unique ID of the program output item. + + - `call_id: String` + + The call ID of the program item. + + - `result: String` + + The result produced by the program item. + + - `status: :completed | :incomplete` + + The terminal status of the program output item. + + - `:completed` + + - `:incomplete` + + - `type: :program_output` + + The type of the item. Always `program_output`. + + - `:program_output` + - `class ResponseToolSearchCall` - `id: String` @@ -45821,107 +50888,111 @@ puts(compacted_response) A tool that runs Python code to help generate a response to a prompt. - - `class ImageGeneration` - - A tool that generates images using the GPT image models. - - - `class LocalShell` - - A tool that allows the model to execute shell commands in a local environment. - - - `class FunctionShellTool` - - A tool that allows the model to execute shell commands. - - - `class CustomTool` - - A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) - - - `class NamespaceTool` - - Groups function/custom tools under a shared namespace. - - - `class ToolSearchTool` - - Hosted or BYOT tool search configuration for deferred tools. - - - `class WebSearchPreviewTool` - - This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - - - `class ApplyPatchTool` - - Allows the assistant to create, delete, or update files using unified diffs. - - - `type: :tool_search_output` - - The type of the item. Always `tool_search_output`. - - - `:tool_search_output` - - - `created_by: String` - - The identifier of the actor that created the item. - - - `class AdditionalTools` - - - `id: String` - - The unique ID of the additional tools item. - - - `role: :unknown | :user | :assistant | 5 more` - - The role that provided the additional tools. - - - `:unknown` - - - `:user` - - - `:assistant` - - - `:system` - - - `:critic` - - - `:discriminator` - - - `:developer` - - - `:tool` - - - `tools: Array[Tool]` - - The additional tool definitions made available at this item. - - - `class FunctionTool` - - Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). - - - `class FileSearchTool` - - A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). - - - `class ComputerTool` - - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - - `class ComputerUsePreviewTool` - - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - - `class WebSearchTool` - - Search the Internet for sources related to the prompt. Learn more about the - [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - - - `class Mcp` - - Give the model access to additional tools via remote Model Context Protocol - (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). - - - `class CodeInterpreter` - - A tool that runs Python code to help generate a response to a prompt. + - `class ProgrammaticToolCalling` + + - `class ImageGeneration` + + A tool that generates images using the GPT image models. + + - `class LocalShell` + + A tool that allows the model to execute shell commands in a local environment. + + - `class FunctionShellTool` + + A tool that allows the model to execute shell commands. + + - `class CustomTool` + + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) + + - `class NamespaceTool` + + Groups function/custom tools under a shared namespace. + + - `class ToolSearchTool` + + Hosted or BYOT tool search configuration for deferred tools. + + - `class WebSearchPreviewTool` + + This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + + - `class ApplyPatchTool` + + Allows the assistant to create, delete, or update files using unified diffs. + + - `type: :tool_search_output` + + The type of the item. Always `tool_search_output`. + + - `:tool_search_output` + + - `created_by: String` + + The identifier of the actor that created the item. + + - `class AdditionalTools` + + - `id: String` + + The unique ID of the additional tools item. + + - `role: :unknown | :user | :assistant | 5 more` + + The role that provided the additional tools. + + - `:unknown` + + - `:user` + + - `:assistant` + + - `:system` + + - `:critic` + + - `:discriminator` + + - `:developer` + + - `:tool` + + - `tools: Array[Tool]` + + The additional tool definitions made available at this item. + + - `class FunctionTool` + + Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). + + - `class FileSearchTool` + + A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). + + - `class ComputerTool` + + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + + - `class ComputerUsePreviewTool` + + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + + - `class WebSearchTool` + + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + + - `class Mcp` + + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). + + - `class CodeInterpreter` + + A tool that runs Python code to help generate a response to a prompt. + + - `class ProgrammaticToolCalling` - `class ImageGeneration` @@ -46171,6 +51242,26 @@ puts(compacted_response) - `:shell_call` + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + - `:program` + - `created_by: String` The ID of the entity that created this tool call. @@ -46251,6 +51342,26 @@ puts(compacted_response) - `:shell_call_output` + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + - `:program` + - `created_by: String` The identifier of the actor that created the item. @@ -46335,6 +51446,26 @@ puts(compacted_response) - `:apply_patch_call` + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + - `:program` + - `created_by: String` The ID of the entity that created this tool call. @@ -46365,6 +51496,26 @@ puts(compacted_response) - `:apply_patch_call_output` + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + - `:program` + - `created_by: String` The ID of the entity that created this tool call output. @@ -46556,7 +51707,7 @@ puts(compacted_response) What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. We generally recommend altering this or `top_p` but not both. - - `tool_choice: ToolChoiceOptions | ToolChoiceAllowed | ToolChoiceTypes | 5 more` + - `tool_choice: ToolChoiceOptions | ToolChoiceAllowed | ToolChoiceTypes | 6 more` How the model should select which tool (or tools) to use when generating a response. See the `tools` parameter to see how to specify which tools @@ -46698,6 +51849,14 @@ puts(compacted_response) - `:custom` + - `class SpecificProgrammaticToolCallingParam` + + - `type: :programmatic_tool_calling` + + The tool to call. Always `programmatic_tool_calling`. + + - `:programmatic_tool_calling` + - `class ToolChoiceApplyPatch` Forces the model to call the apply_patch tool when executing a tool call. @@ -46768,6 +51927,8 @@ puts(compacted_response) A tool that runs Python code to help generate a response to a prompt. + - `class ProgrammaticToolCalling` + - `class ImageGeneration` A tool that generates images using the GPT image models. @@ -46994,9 +52155,32 @@ puts(compacted_response) Used by OpenAI to cache responses for similar requests to optimize your cache hit rates. Replaces the `user` field. [Learn more](https://platform.openai.com/docs/guides/prompt-caching). + - `prompt_cache_options: PromptCacheOptions{ mode, ttl}` + + The prompt-caching options that were applied to the response. Supported for `gpt-5.6` and later models. + + - `mode: :implicit | :explicit` + + Whether implicit prompt-cache breakpoints were enabled. + + - `:implicit` + + - `:explicit` + + - `ttl: :"30m"` + + The minimum lifetime applied to each cache breakpoint. + + - `:"30m"` + - `prompt_cache_retention: :in_memory | :"24h"` + Deprecated. Use `prompt_cache_options.ttl` instead. + The retention policy for the prompt cache. Set to `24h` to enable extended prompt caching, which keeps cached prefixes active for longer, up to a maximum of 24 hours. [Learn more](https://platform.openai.com/docs/guides/prompt-caching#prompt-cache-retention). + This field expresses a maximum retention policy, while + `prompt_cache_options.ttl` expresses a minimum cache lifetime. The two + fields are independent and do not interact. For `gpt-5.5`, `gpt-5.5-pro`, and future models, only `24h` is supported. For older models that support both `in_memory` and `24h`, the default depends on your organization's data retention policy: @@ -47029,16 +52213,13 @@ puts(compacted_response) - `effort: ReasoningEffort` - Constrains effort on reasoning for - [reasoning models](https://platform.openai.com/docs/guides/reasoning). - Currently supported values are `none`, `minimal`, `low`, `medium`, `high`, and `xhigh`. Reducing - reasoning effort can result in faster responses and fewer tokens used - on reasoning in a response. - - - `gpt-5.1` defaults to `none`, which does not perform reasoning. The supported reasoning values for `gpt-5.1` are `none`, `low`, `medium`, and `high`. Tool calls are supported for all reasoning values in gpt-5.1. - - All models before `gpt-5.1` default to `medium` reasoning effort, and do not support `none`. - - The `gpt-5-pro` model defaults to (and only supports) `high` reasoning effort. - - `xhigh` is supported for all models after `gpt-5.1-codex-max`. + Constrains effort on reasoning for reasoning models. Currently supported + values are `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max`. + Reducing reasoning effort can result in faster responses and fewer tokens + used on reasoning in a response. Not all reasoning models support every + value. See the + [reasoning guide](https://platform.openai.com/docs/guides/reasoning) + for model-specific support. - `:none` @@ -47052,6 +52233,8 @@ puts(compacted_response) - `:xhigh` + - `:max` + - `generate_summary: :auto | :concise | :detailed` **Deprecated:** use `summary` instead. @@ -47066,6 +52249,24 @@ puts(compacted_response) - `:detailed` + - `mode: String | :standard | :pro` + + Controls the reasoning execution mode for the request. + + When returned on a response, this is the effective execution mode. + + - `String = String` + + - `Mode = :standard | :pro` + + Controls the reasoning execution mode for the request. + + When returned on a response, this is the effective execution mode. + + - `:standard` + + - `:pro` + - `summary: :auto | :concise | :detailed` A summary of the reasoning performed by the model. This can be @@ -47246,10 +52447,14 @@ puts(compacted_response) The number of input tokens. - - `input_tokens_details: InputTokensDetails{ cached_tokens}` + - `input_tokens_details: InputTokensDetails{ cache_write_tokens, cached_tokens}` A detailed breakdown of the input tokens. + - `cache_write_tokens: Integer` + + The number of input tokens that were written to the cache. + - `cached_tokens: Integer` The number of tokens that were retrieved from the cache. @@ -47315,6 +52520,26 @@ puts(compacted_response) The unique ID of the custom tool call in the OpenAI platform. + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + - `:program` + - `namespace: String` The namespace of the custom tool being called. @@ -47437,6 +52662,16 @@ puts(compacted_response) - `:input_text` + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + + 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`. + + - `:explicit` + - `class ResponseInputImage` An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). @@ -47467,6 +52702,16 @@ puts(compacted_response) The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + + 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`. + + - `:explicit` + - `class ResponseInputFile` A file input to the model. @@ -47477,9 +52722,11 @@ puts(compacted_response) - `:input_file` - - `detail: :low | :high` + - `detail: :auto | :low | :high` - The detail level of the file to be sent to the model. Use `low` for the default rendering behavior, or `high` to render the file at higher quality. Defaults to `low`. + The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. + + - `:auto` - `:low` @@ -47501,6 +52748,16 @@ puts(compacted_response) The name of the file to be sent to the model. + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + + 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`. + + - `:explicit` + - `type: :custom_tool_call_output` The type of the custom tool call output. Always `custom_tool_call_output`. @@ -47511,6 +52768,30 @@ puts(compacted_response) The unique ID of the custom tool call output in the OpenAI platform. + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + The caller type. Always `direct`. + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + The caller type. Always `program`. + + - `:program` + ### Response Custom Tool Call Output Item - `class ResponseCustomToolCallOutputItem` @@ -47542,7 +52823,7 @@ puts(compacted_response) An error object returned when the model fails to generate a Response. - - `code: :server_error | :rate_limit_exceeded | :invalid_prompt | 15 more` + - `code: :server_error | :rate_limit_exceeded | :invalid_prompt | 16 more` The error code for the response. @@ -47552,6 +52833,8 @@ puts(compacted_response) - `:invalid_prompt` + - `:bio_policy` + - `:vector_store_timeout` - `:invalid_image` @@ -47636,7 +52919,7 @@ puts(compacted_response) An error object returned when the model fails to generate a Response. - - `code: :server_error | :rate_limit_exceeded | :invalid_prompt | 15 more` + - `code: :server_error | :rate_limit_exceeded | :invalid_prompt | 16 more` The error code for the response. @@ -47646,6 +52929,8 @@ puts(compacted_response) - `:invalid_prompt` + - `:bio_policy` + - `:vector_store_timeout` - `:invalid_image` @@ -47746,6 +53031,16 @@ puts(compacted_response) - `:input_text` + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + + 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`. + + - `:explicit` + - `class ResponseInputImage` An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). @@ -47776,6 +53071,16 @@ puts(compacted_response) The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + + 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`. + + - `:explicit` + - `class ResponseInputFile` A file input to the model. @@ -47786,9 +53091,11 @@ puts(compacted_response) - `:input_file` - - `detail: :low | :high` + - `detail: :auto | :low | :high` - The detail level of the file to be sent to the model. Use `low` for the default rendering behavior, or `high` to render the file at higher quality. Defaults to `low`. + The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. + + - `:auto` - `:low` @@ -47810,6 +53117,16 @@ puts(compacted_response) The name of the file to be sent to the model. + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + + 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`. + + - `:explicit` + - `role: :user | :assistant | :system | :developer` The role of the message input. One of `user`, `assistant`, `system`, or @@ -48757,6 +54074,26 @@ puts(compacted_response) The unique ID of the function tool call. + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + - `:program` + - `namespace: String` The namespace of the function to run. @@ -48806,6 +54143,16 @@ puts(compacted_response) - `:input_text` + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + + 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`. + + - `:explicit` + - `class ResponseInputImageContent` An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) @@ -48836,6 +54183,16 @@ puts(compacted_response) The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + + 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`. + + - `:explicit` + - `class ResponseInputFileContent` A file input to the model. @@ -48846,9 +54203,11 @@ puts(compacted_response) - `:input_file` - - `detail: :low | :high` + - `detail: :auto | :low | :high` + + The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. - The detail level of the file to be sent to the model. Use `low` for the default rendering behavior, or `high` to render the file at higher quality. Defaults to `low`. + - `:auto` - `:low` @@ -48870,6 +54229,16 @@ puts(compacted_response) The name of the file to be sent to the model. + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + + 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`. + + - `:explicit` + - `type: :function_call_output` The type of the function tool call output. Always `function_call_output`. @@ -48880,6 +54249,30 @@ puts(compacted_response) The unique ID of the function tool call output. Populated when this item is returned via API. + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + The caller type. Always `direct`. + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + The caller type. Always `program`. + + - `:program` + - `status: :in_progress | :completed | :incomplete` The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. @@ -48948,7 +54341,7 @@ puts(compacted_response) - `strict: bool` - Whether to enforce strict parameter validation. Default `true`. + Whether strict parameter validation is enforced for this function tool. - `type: :function` @@ -48956,6 +54349,14 @@ puts(compacted_response) - `:function` + - `allowed_callers: Array[:direct | :programmatic]` + + The tool invocation context(s). + + - `:direct` + + - `:programmatic` + - `defer_loading: bool` Whether this function is deferred and loaded via tool search. @@ -48964,6 +54365,10 @@ puts(compacted_response) A description of the function. Used by the model to determine whether or not to call the function. + - `output_schema: Hash[Symbol, untyped]` + + A JSON schema object describing the JSON value encoded in string outputs for this function. + - `class FileSearchTool` A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). @@ -49019,7 +54424,7 @@ puts(compacted_response) - `:nin` - - `value: String | Float | bool | Array[String | Float]` + - `value: String | Float | bool | Array[untyped]` The value to compare against the attribute key; supports string, number, or boolean types. @@ -49029,11 +54434,7 @@ puts(compacted_response) - `UnionMember2 = bool` - - `UnionMember3 = Array[String | Float]` - - - `String = String` - - - `Float = Float` + - `UnionMember3 = Array[untyped]` - `class CompoundFilter` @@ -49206,6 +54607,14 @@ puts(compacted_response) - `:mcp` + - `allowed_callers: Array[:direct | :programmatic]` + + The tool invocation context(s). + + - `:direct` + + - `:programmatic` + - `allowed_tools: Array[String] | McpToolFilter{ read_only, tool_names}` List of allowed tool names or a filter object. @@ -49424,6 +54833,22 @@ puts(compacted_response) - `:code_interpreter` + - `allowed_callers: Array[:direct | :programmatic]` + + The tool invocation context(s). + + - `:direct` + + - `:programmatic` + + - `class ProgrammaticToolCalling` + + - `type: :programmatic_tool_calling` + + The type of the tool. Always `programmatic_tool_calling`. + + - `:programmatic_tool_calling` + - `class ImageGeneration` A tool that generates images using the GPT image models. @@ -49587,6 +55012,14 @@ puts(compacted_response) - `:shell` + - `allowed_callers: Array[:direct | :programmatic]` + + The tool invocation context(s). + + - `:direct` + + - `:programmatic` + - `environment: ContainerAuto | LocalEnvironment | ContainerReference` - `class ContainerAuto` @@ -49727,6 +55160,14 @@ puts(compacted_response) - `:custom` + - `allowed_callers: Array[:direct | :programmatic]` + + The tool invocation context(s). + + - `:direct` + + - `:programmatic` + - `defer_loading: bool` Whether this tool should be deferred and discovered via tool search. @@ -49783,7 +55224,7 @@ puts(compacted_response) The namespace name used in tool calls (for example, `crm`). - - `tools: Array[Function{ name, type, defer_loading, 3 more} | CustomTool]` + - `tools: Array[Function{ name, type, allowed_callers, 5 more} | CustomTool]` The function/custom tools available inside this namespace. @@ -49795,16 +55236,30 @@ puts(compacted_response) - `:function` + - `allowed_callers: Array[:direct | :programmatic]` + + The tool invocation context(s). + + - `:direct` + + - `:programmatic` + - `defer_loading: bool` Whether this function should be deferred and discovered via tool search. - `description: String` + - `output_schema: Hash[Symbol, untyped]` + + A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. + - `parameters: untyped` - `strict: bool` + Whether to enforce strict parameter validation. If omitted, Responses attempts to use strict validation when the schema is compatible, and falls back to non-strict validation otherwise. + - `class CustomTool` A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) @@ -49905,6 +55360,14 @@ puts(compacted_response) - `:apply_patch` + - `allowed_callers: Array[:direct | :programmatic]` + + The tool invocation context(s). + + - `:direct` + + - `:programmatic` + - `type: :tool_search_output` The item type. Always `tool_search_output`. @@ -49979,6 +55442,8 @@ puts(compacted_response) A tool that runs Python code to help generate a response to a prompt. + - `class ProgrammaticToolCalling` + - `class ImageGeneration` A tool that generates images using the GPT image models. @@ -50319,6 +55784,30 @@ puts(compacted_response) The unique ID of the shell tool call. Populated when this item is returned via API. + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + The caller type. Always `direct`. + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + The caller type. Always `program`. + + - `:program` + - `environment: LocalEnvironment | ContainerReference` The environment to execute the shell commands in. @@ -50395,6 +55884,30 @@ puts(compacted_response) The unique ID of the shell tool call output. Populated when this item is returned via API. + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + The caller type. Always `direct`. + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + The caller type. Always `program`. + + - `:program` + - `max_output_length: Integer` The maximum number of UTF-8 characters captured for this shell call's combined output. @@ -50489,6 +56002,30 @@ puts(compacted_response) The unique ID of the apply patch tool call. Populated when this item is returned via API. + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + The caller type. Always `direct`. + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + The caller type. Always `program`. + + - `:program` + - `class ApplyPatchCallOutput` The streamed output emitted by an apply patch tool call. @@ -50515,6 +56052,30 @@ puts(compacted_response) The unique ID of the apply patch tool call output. Populated when this item is returned via API. + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + The caller type. Always `direct`. + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + The caller type. Always `program`. + + - `:program` + - `output: String` Optional human-readable log text from the apply patch tool (e.g., patch results or errors). @@ -50709,6 +56270,30 @@ puts(compacted_response) The unique ID of the custom tool call output in the OpenAI platform. + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + The caller type. Always `direct`. + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + The caller type. Always `program`. + + - `:program` + - `class ResponseCustomToolCall` A call to a custom tool created by the model. @@ -50735,6 +56320,26 @@ puts(compacted_response) The unique ID of the custom tool call in the OpenAI platform. + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + - `:program` + - `namespace: String` The namespace of the custom tool being called. @@ -50763,6 +56368,58 @@ puts(compacted_response) - `:item_reference` + - `class Program` + + - `id: String` + + The unique ID of this program item. + + - `call_id: String` + + The stable call ID of the program item. + + - `code: String` + + The JavaScript source executed by programmatic tool calling. + + - `fingerprint: String` + + Opaque program replay fingerprint that must be round-tripped. + + - `type: :program` + + The item type. Always `program`. + + - `:program` + + - `class ProgramOutput` + + - `id: String` + + The unique ID of this program output item. + + - `call_id: String` + + The call ID of the program item. + + - `result: String` + + The result produced by the program item. + + - `status: :completed | :incomplete` + + The terminal status of the program output. + + - `:completed` + + - `:incomplete` + + - `type: :program_output` + + The item type. Always `program_output`. + + - `:program_output` + - `metadata: Metadata` Set of 16 key-value pairs that can be attached to an object. This can be @@ -50781,7 +56438,13 @@ puts(compacted_response) - `String = String` - - `ChatModel = :"gpt-5.4" | :"gpt-5.4-mini" | :"gpt-5.4-nano" | 75 more` + - `ChatModel = :"gpt-5.6-sol" | :"gpt-5.6-terra" | :"gpt-5.6-luna" | 78 more` + + - `:"gpt-5.6-sol"` + + - `:"gpt-5.6-terra"` + + - `:"gpt-5.6-luna"` - `:"gpt-5.4"` @@ -51052,6 +56715,30 @@ puts(compacted_response) - `:function_call_output` + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + The caller type. Always `direct`. + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + The caller type. Always `program`. + + - `:program` + - `created_by: String` The identifier of the actor that created the item. @@ -51127,6 +56814,58 @@ puts(compacted_response) for subsequent turns of a conversation if you are manually [managing context](https://platform.openai.com/docs/guides/conversation-state). + - `class Program` + + - `id: String` + + The unique ID of the program item. + + - `call_id: String` + + The stable call ID of the program item. + + - `code: String` + + The JavaScript source executed by programmatic tool calling. + + - `fingerprint: String` + + Opaque program replay fingerprint that must be round-tripped. + + - `type: :program` + + The type of the item. Always `program`. + + - `:program` + + - `class ProgramOutput` + + - `id: String` + + The unique ID of the program output item. + + - `call_id: String` + + The call ID of the program item. + + - `result: String` + + The result produced by the program item. + + - `status: :completed | :incomplete` + + The terminal status of the program output item. + + - `:completed` + + - `:incomplete` + + - `type: :program_output` + + The type of the item. Always `program_output`. + + - `:program_output` + - `class ResponseToolSearchCall` - `id: String` @@ -51231,6 +56970,8 @@ puts(compacted_response) A tool that runs Python code to help generate a response to a prompt. + - `class ProgrammaticToolCalling` + - `class ImageGeneration` A tool that generates images using the GPT image models. @@ -51333,6 +57074,8 @@ puts(compacted_response) A tool that runs Python code to help generate a response to a prompt. + - `class ProgrammaticToolCalling` + - `class ImageGeneration` A tool that generates images using the GPT image models. @@ -51581,6 +57324,26 @@ puts(compacted_response) - `:shell_call` + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + - `:program` + - `created_by: String` The ID of the entity that created this tool call. @@ -51661,6 +57424,26 @@ puts(compacted_response) - `:shell_call_output` + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + - `:program` + - `created_by: String` The identifier of the actor that created the item. @@ -51745,6 +57528,26 @@ puts(compacted_response) - `:apply_patch_call` + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + - `:program` + - `created_by: String` The ID of the entity that created this tool call. @@ -51775,6 +57578,26 @@ puts(compacted_response) - `:apply_patch_call_output` + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + - `:program` + - `created_by: String` The ID of the entity that created this tool call output. @@ -51966,7 +57789,7 @@ puts(compacted_response) What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. We generally recommend altering this or `top_p` but not both. - - `tool_choice: ToolChoiceOptions | ToolChoiceAllowed | ToolChoiceTypes | 5 more` + - `tool_choice: ToolChoiceOptions | ToolChoiceAllowed | ToolChoiceTypes | 6 more` How the model should select which tool (or tools) to use when generating a response. See the `tools` parameter to see how to specify which tools @@ -52108,6 +57931,14 @@ puts(compacted_response) - `:custom` + - `class SpecificProgrammaticToolCallingParam` + + - `type: :programmatic_tool_calling` + + The tool to call. Always `programmatic_tool_calling`. + + - `:programmatic_tool_calling` + - `class ToolChoiceApplyPatch` Forces the model to call the apply_patch tool when executing a tool call. @@ -52178,6 +58009,8 @@ puts(compacted_response) A tool that runs Python code to help generate a response to a prompt. + - `class ProgrammaticToolCalling` + - `class ImageGeneration` A tool that generates images using the GPT image models. @@ -52404,9 +58237,32 @@ puts(compacted_response) Used by OpenAI to cache responses for similar requests to optimize your cache hit rates. Replaces the `user` field. [Learn more](https://platform.openai.com/docs/guides/prompt-caching). + - `prompt_cache_options: PromptCacheOptions{ mode, ttl}` + + The prompt-caching options that were applied to the response. Supported for `gpt-5.6` and later models. + + - `mode: :implicit | :explicit` + + Whether implicit prompt-cache breakpoints were enabled. + + - `:implicit` + + - `:explicit` + + - `ttl: :"30m"` + + The minimum lifetime applied to each cache breakpoint. + + - `:"30m"` + - `prompt_cache_retention: :in_memory | :"24h"` + Deprecated. Use `prompt_cache_options.ttl` instead. + The retention policy for the prompt cache. Set to `24h` to enable extended prompt caching, which keeps cached prefixes active for longer, up to a maximum of 24 hours. [Learn more](https://platform.openai.com/docs/guides/prompt-caching#prompt-cache-retention). + This field expresses a maximum retention policy, while + `prompt_cache_options.ttl` expresses a minimum cache lifetime. The two + fields are independent and do not interact. For `gpt-5.5`, `gpt-5.5-pro`, and future models, only `24h` is supported. For older models that support both `in_memory` and `24h`, the default depends on your organization's data retention policy: @@ -52439,16 +58295,13 @@ puts(compacted_response) - `effort: ReasoningEffort` - Constrains effort on reasoning for - [reasoning models](https://platform.openai.com/docs/guides/reasoning). - Currently supported values are `none`, `minimal`, `low`, `medium`, `high`, and `xhigh`. Reducing - reasoning effort can result in faster responses and fewer tokens used - on reasoning in a response. - - - `gpt-5.1` defaults to `none`, which does not perform reasoning. The supported reasoning values for `gpt-5.1` are `none`, `low`, `medium`, and `high`. Tool calls are supported for all reasoning values in gpt-5.1. - - All models before `gpt-5.1` default to `medium` reasoning effort, and do not support `none`. - - The `gpt-5-pro` model defaults to (and only supports) `high` reasoning effort. - - `xhigh` is supported for all models after `gpt-5.1-codex-max`. + Constrains effort on reasoning for reasoning models. Currently supported + values are `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max`. + Reducing reasoning effort can result in faster responses and fewer tokens + used on reasoning in a response. Not all reasoning models support every + value. See the + [reasoning guide](https://platform.openai.com/docs/guides/reasoning) + for model-specific support. - `:none` @@ -52462,6 +58315,8 @@ puts(compacted_response) - `:xhigh` + - `:max` + - `generate_summary: :auto | :concise | :detailed` **Deprecated:** use `summary` instead. @@ -52476,6 +58331,24 @@ puts(compacted_response) - `:detailed` + - `mode: String | :standard | :pro` + + Controls the reasoning execution mode for the request. + + When returned on a response, this is the effective execution mode. + + - `String = String` + + - `Mode = :standard | :pro` + + Controls the reasoning execution mode for the request. + + When returned on a response, this is the effective execution mode. + + - `:standard` + + - `:pro` + - `summary: :auto | :concise | :detailed` A summary of the reasoning performed by the model. This can be @@ -52656,10 +58529,14 @@ puts(compacted_response) The number of input tokens. - - `input_tokens_details: InputTokensDetails{ cached_tokens}` + - `input_tokens_details: InputTokensDetails{ cache_write_tokens, cached_tokens}` A detailed breakdown of the input tokens. + - `cache_write_tokens: Integer` + + The number of input tokens that were written to the cache. + - `cached_tokens: Integer` The number of tokens that were retrieved from the cache. @@ -53028,6 +58905,16 @@ puts(compacted_response) - `:input_text` + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + + 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`. + + - `:explicit` + - `class ResponseInputImageContent` An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) @@ -53058,6 +58945,16 @@ puts(compacted_response) The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + + 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`. + + - `:explicit` + - `class ResponseInputFileContent` A file input to the model. @@ -53068,9 +58965,11 @@ puts(compacted_response) - `:input_file` - - `detail: :low | :high` + - `detail: :auto | :low | :high` + + The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. - The detail level of the file to be sent to the model. Use `low` for the default rendering behavior, or `high` to render the file at higher quality. Defaults to `low`. + - `:auto` - `:low` @@ -53092,6 +58991,16 @@ puts(compacted_response) The name of the file to be sent to the model. + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + + 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`. + + - `:explicit` + ### Response Function Call Output Item List - `ResponseFunctionCallOutputItemList = Array[ResponseFunctionCallOutputItem]` @@ -53112,6 +59021,16 @@ puts(compacted_response) - `:input_text` + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + + 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`. + + - `:explicit` + - `class ResponseInputImageContent` An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) @@ -53142,6 +59061,16 @@ puts(compacted_response) The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + + 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`. + + - `:explicit` + - `class ResponseInputFileContent` A file input to the model. @@ -53152,9 +59081,11 @@ puts(compacted_response) - `:input_file` - - `detail: :low | :high` + - `detail: :auto | :low | :high` - The detail level of the file to be sent to the model. Use `low` for the default rendering behavior, or `high` to render the file at higher quality. Defaults to `low`. + The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. + + - `:auto` - `:low` @@ -53176,6 +59107,16 @@ puts(compacted_response) The name of the file to be sent to the model. + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + + 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`. + + - `:explicit` + ### Response Function Shell Call Output Content - `class ResponseFunctionShellCallOutputContent` @@ -53288,6 +59229,26 @@ puts(compacted_response) - `:shell_call` + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + - `:program` + - `created_by: String` The ID of the entity that created this tool call. @@ -53370,6 +59331,26 @@ puts(compacted_response) - `:shell_call_output` + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + - `:program` + - `created_by: String` The identifier of the actor that created the item. @@ -53403,6 +59384,26 @@ puts(compacted_response) The unique ID of the function tool call. + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + - `:program` + - `namespace: String` The namespace of the function to run. @@ -53483,6 +59484,16 @@ puts(compacted_response) - `:input_text` + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + + 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`. + + - `:explicit` + - `class ResponseInputImage` An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). @@ -53513,6 +59524,16 @@ puts(compacted_response) The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + + 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`. + + - `:explicit` + - `class ResponseInputFile` A file input to the model. @@ -53523,9 +59544,11 @@ puts(compacted_response) - `:input_file` - - `detail: :low | :high` + - `detail: :auto | :low | :high` + + The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. - The detail level of the file to be sent to the model. Use `low` for the default rendering behavior, or `high` to render the file at higher quality. Defaults to `low`. + - `:auto` - `:low` @@ -53547,6 +59570,16 @@ puts(compacted_response) The name of the file to be sent to the model. + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + + 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`. + + - `:explicit` + - `status: :in_progress | :completed | :incomplete` The status of the item. One of `in_progress`, `completed`, or @@ -53564,6 +59597,30 @@ puts(compacted_response) - `:function_call_output` + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + The caller type. Always `direct`. + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + The caller type. Always `program`. + + - `:program` + - `created_by: String` The identifier of the actor that created the item. @@ -53792,7 +59849,7 @@ puts(compacted_response) An error object returned when the model fails to generate a Response. - - `code: :server_error | :rate_limit_exceeded | :invalid_prompt | 15 more` + - `code: :server_error | :rate_limit_exceeded | :invalid_prompt | 16 more` The error code for the response. @@ -53802,6 +59859,8 @@ puts(compacted_response) - `:invalid_prompt` + - `:bio_policy` + - `:vector_store_timeout` - `:invalid_image` @@ -53902,6 +59961,16 @@ puts(compacted_response) - `:input_text` + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + + 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`. + + - `:explicit` + - `class ResponseInputImage` An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). @@ -53932,6 +60001,16 @@ puts(compacted_response) The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + + 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`. + + - `:explicit` + - `class ResponseInputFile` A file input to the model. @@ -53942,9 +60021,11 @@ puts(compacted_response) - `:input_file` - - `detail: :low | :high` + - `detail: :auto | :low | :high` - The detail level of the file to be sent to the model. Use `low` for the default rendering behavior, or `high` to render the file at higher quality. Defaults to `low`. + The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. + + - `:auto` - `:low` @@ -53966,6 +60047,16 @@ puts(compacted_response) The name of the file to be sent to the model. + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + + 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`. + + - `:explicit` + - `role: :user | :assistant | :system | :developer` The role of the message input. One of `user`, `assistant`, `system`, or @@ -54913,6 +61004,26 @@ puts(compacted_response) The unique ID of the function tool call. + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + - `:program` + - `namespace: String` The namespace of the function to run. @@ -54962,6 +61073,16 @@ puts(compacted_response) - `:input_text` + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + + 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`. + + - `:explicit` + - `class ResponseInputImageContent` An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) @@ -54992,6 +61113,16 @@ puts(compacted_response) The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + + 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`. + + - `:explicit` + - `class ResponseInputFileContent` A file input to the model. @@ -55002,9 +61133,11 @@ puts(compacted_response) - `:input_file` - - `detail: :low | :high` + - `detail: :auto | :low | :high` + + The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. - The detail level of the file to be sent to the model. Use `low` for the default rendering behavior, or `high` to render the file at higher quality. Defaults to `low`. + - `:auto` - `:low` @@ -55026,6 +61159,16 @@ puts(compacted_response) The name of the file to be sent to the model. + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + + 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`. + + - `:explicit` + - `type: :function_call_output` The type of the function tool call output. Always `function_call_output`. @@ -55036,6 +61179,30 @@ puts(compacted_response) The unique ID of the function tool call output. Populated when this item is returned via API. + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + The caller type. Always `direct`. + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + The caller type. Always `program`. + + - `:program` + - `status: :in_progress | :completed | :incomplete` The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. @@ -55104,7 +61271,7 @@ puts(compacted_response) - `strict: bool` - Whether to enforce strict parameter validation. Default `true`. + Whether strict parameter validation is enforced for this function tool. - `type: :function` @@ -55112,6 +61279,14 @@ puts(compacted_response) - `:function` + - `allowed_callers: Array[:direct | :programmatic]` + + The tool invocation context(s). + + - `:direct` + + - `:programmatic` + - `defer_loading: bool` Whether this function is deferred and loaded via tool search. @@ -55120,6 +61295,10 @@ puts(compacted_response) A description of the function. Used by the model to determine whether or not to call the function. + - `output_schema: Hash[Symbol, untyped]` + + A JSON schema object describing the JSON value encoded in string outputs for this function. + - `class FileSearchTool` A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). @@ -55175,7 +61354,7 @@ puts(compacted_response) - `:nin` - - `value: String | Float | bool | Array[String | Float]` + - `value: String | Float | bool | Array[untyped]` The value to compare against the attribute key; supports string, number, or boolean types. @@ -55185,11 +61364,7 @@ puts(compacted_response) - `UnionMember2 = bool` - - `UnionMember3 = Array[String | Float]` - - - `String = String` - - - `Float = Float` + - `UnionMember3 = Array[untyped]` - `class CompoundFilter` @@ -55362,6 +61537,14 @@ puts(compacted_response) - `:mcp` + - `allowed_callers: Array[:direct | :programmatic]` + + The tool invocation context(s). + + - `:direct` + + - `:programmatic` + - `allowed_tools: Array[String] | McpToolFilter{ read_only, tool_names}` List of allowed tool names or a filter object. @@ -55580,6 +61763,22 @@ puts(compacted_response) - `:code_interpreter` + - `allowed_callers: Array[:direct | :programmatic]` + + The tool invocation context(s). + + - `:direct` + + - `:programmatic` + + - `class ProgrammaticToolCalling` + + - `type: :programmatic_tool_calling` + + The type of the tool. Always `programmatic_tool_calling`. + + - `:programmatic_tool_calling` + - `class ImageGeneration` A tool that generates images using the GPT image models. @@ -55743,6 +61942,14 @@ puts(compacted_response) - `:shell` + - `allowed_callers: Array[:direct | :programmatic]` + + The tool invocation context(s). + + - `:direct` + + - `:programmatic` + - `environment: ContainerAuto | LocalEnvironment | ContainerReference` - `class ContainerAuto` @@ -55883,6 +62090,14 @@ puts(compacted_response) - `:custom` + - `allowed_callers: Array[:direct | :programmatic]` + + The tool invocation context(s). + + - `:direct` + + - `:programmatic` + - `defer_loading: bool` Whether this tool should be deferred and discovered via tool search. @@ -55939,7 +62154,7 @@ puts(compacted_response) The namespace name used in tool calls (for example, `crm`). - - `tools: Array[Function{ name, type, defer_loading, 3 more} | CustomTool]` + - `tools: Array[Function{ name, type, allowed_callers, 5 more} | CustomTool]` The function/custom tools available inside this namespace. @@ -55951,16 +62166,30 @@ puts(compacted_response) - `:function` + - `allowed_callers: Array[:direct | :programmatic]` + + The tool invocation context(s). + + - `:direct` + + - `:programmatic` + - `defer_loading: bool` Whether this function should be deferred and discovered via tool search. - `description: String` + - `output_schema: Hash[Symbol, untyped]` + + A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. + - `parameters: untyped` - `strict: bool` + Whether to enforce strict parameter validation. If omitted, Responses attempts to use strict validation when the schema is compatible, and falls back to non-strict validation otherwise. + - `class CustomTool` A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) @@ -56061,6 +62290,14 @@ puts(compacted_response) - `:apply_patch` + - `allowed_callers: Array[:direct | :programmatic]` + + The tool invocation context(s). + + - `:direct` + + - `:programmatic` + - `type: :tool_search_output` The item type. Always `tool_search_output`. @@ -56135,6 +62372,8 @@ puts(compacted_response) A tool that runs Python code to help generate a response to a prompt. + - `class ProgrammaticToolCalling` + - `class ImageGeneration` A tool that generates images using the GPT image models. @@ -56475,6 +62714,30 @@ puts(compacted_response) The unique ID of the shell tool call. Populated when this item is returned via API. + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + The caller type. Always `direct`. + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + The caller type. Always `program`. + + - `:program` + - `environment: LocalEnvironment | ContainerReference` The environment to execute the shell commands in. @@ -56551,6 +62814,30 @@ puts(compacted_response) The unique ID of the shell tool call output. Populated when this item is returned via API. + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + The caller type. Always `direct`. + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + The caller type. Always `program`. + + - `:program` + - `max_output_length: Integer` The maximum number of UTF-8 characters captured for this shell call's combined output. @@ -56645,6 +62932,30 @@ puts(compacted_response) The unique ID of the apply patch tool call. Populated when this item is returned via API. + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + The caller type. Always `direct`. + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + The caller type. Always `program`. + + - `:program` + - `class ApplyPatchCallOutput` The streamed output emitted by an apply patch tool call. @@ -56671,6 +62982,30 @@ puts(compacted_response) The unique ID of the apply patch tool call output. Populated when this item is returned via API. + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + The caller type. Always `direct`. + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + The caller type. Always `program`. + + - `:program` + - `output: String` Optional human-readable log text from the apply patch tool (e.g., patch results or errors). @@ -56865,6 +63200,30 @@ puts(compacted_response) The unique ID of the custom tool call output in the OpenAI platform. + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + The caller type. Always `direct`. + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + The caller type. Always `program`. + + - `:program` + - `class ResponseCustomToolCall` A call to a custom tool created by the model. @@ -56891,6 +63250,26 @@ puts(compacted_response) The unique ID of the custom tool call in the OpenAI platform. + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + - `:program` + - `namespace: String` The namespace of the custom tool being called. @@ -56919,6 +63298,58 @@ puts(compacted_response) - `:item_reference` + - `class Program` + + - `id: String` + + The unique ID of this program item. + + - `call_id: String` + + The stable call ID of the program item. + + - `code: String` + + The JavaScript source executed by programmatic tool calling. + + - `fingerprint: String` + + Opaque program replay fingerprint that must be round-tripped. + + - `type: :program` + + The item type. Always `program`. + + - `:program` + + - `class ProgramOutput` + + - `id: String` + + The unique ID of this program output item. + + - `call_id: String` + + The call ID of the program item. + + - `result: String` + + The result produced by the program item. + + - `status: :completed | :incomplete` + + The terminal status of the program output. + + - `:completed` + + - `:incomplete` + + - `type: :program_output` + + The item type. Always `program_output`. + + - `:program_output` + - `metadata: Metadata` Set of 16 key-value pairs that can be attached to an object. This can be @@ -56937,7 +63368,13 @@ puts(compacted_response) - `String = String` - - `ChatModel = :"gpt-5.4" | :"gpt-5.4-mini" | :"gpt-5.4-nano" | 75 more` + - `ChatModel = :"gpt-5.6-sol" | :"gpt-5.6-terra" | :"gpt-5.6-luna" | 78 more` + + - `:"gpt-5.6-sol"` + + - `:"gpt-5.6-terra"` + + - `:"gpt-5.6-luna"` - `:"gpt-5.4"` @@ -57208,6 +63645,30 @@ puts(compacted_response) - `:function_call_output` + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + The caller type. Always `direct`. + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + The caller type. Always `program`. + + - `:program` + - `created_by: String` The identifier of the actor that created the item. @@ -57283,6 +63744,58 @@ puts(compacted_response) for subsequent turns of a conversation if you are manually [managing context](https://platform.openai.com/docs/guides/conversation-state). + - `class Program` + + - `id: String` + + The unique ID of the program item. + + - `call_id: String` + + The stable call ID of the program item. + + - `code: String` + + The JavaScript source executed by programmatic tool calling. + + - `fingerprint: String` + + Opaque program replay fingerprint that must be round-tripped. + + - `type: :program` + + The type of the item. Always `program`. + + - `:program` + + - `class ProgramOutput` + + - `id: String` + + The unique ID of the program output item. + + - `call_id: String` + + The call ID of the program item. + + - `result: String` + + The result produced by the program item. + + - `status: :completed | :incomplete` + + The terminal status of the program output item. + + - `:completed` + + - `:incomplete` + + - `type: :program_output` + + The type of the item. Always `program_output`. + + - `:program_output` + - `class ResponseToolSearchCall` - `id: String` @@ -57387,6 +63900,8 @@ puts(compacted_response) A tool that runs Python code to help generate a response to a prompt. + - `class ProgrammaticToolCalling` + - `class ImageGeneration` A tool that generates images using the GPT image models. @@ -57489,6 +64004,8 @@ puts(compacted_response) A tool that runs Python code to help generate a response to a prompt. + - `class ProgrammaticToolCalling` + - `class ImageGeneration` A tool that generates images using the GPT image models. @@ -57737,6 +64254,26 @@ puts(compacted_response) - `:shell_call` + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + - `:program` + - `created_by: String` The ID of the entity that created this tool call. @@ -57817,6 +64354,26 @@ puts(compacted_response) - `:shell_call_output` + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + - `:program` + - `created_by: String` The identifier of the actor that created the item. @@ -57901,6 +64458,26 @@ puts(compacted_response) - `:apply_patch_call` + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + - `:program` + - `created_by: String` The ID of the entity that created this tool call. @@ -57931,6 +64508,26 @@ puts(compacted_response) - `:apply_patch_call_output` + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + - `:program` + - `created_by: String` The ID of the entity that created this tool call output. @@ -58122,7 +64719,7 @@ puts(compacted_response) What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. We generally recommend altering this or `top_p` but not both. - - `tool_choice: ToolChoiceOptions | ToolChoiceAllowed | ToolChoiceTypes | 5 more` + - `tool_choice: ToolChoiceOptions | ToolChoiceAllowed | ToolChoiceTypes | 6 more` How the model should select which tool (or tools) to use when generating a response. See the `tools` parameter to see how to specify which tools @@ -58264,6 +64861,14 @@ puts(compacted_response) - `:custom` + - `class SpecificProgrammaticToolCallingParam` + + - `type: :programmatic_tool_calling` + + The tool to call. Always `programmatic_tool_calling`. + + - `:programmatic_tool_calling` + - `class ToolChoiceApplyPatch` Forces the model to call the apply_patch tool when executing a tool call. @@ -58334,6 +64939,8 @@ puts(compacted_response) A tool that runs Python code to help generate a response to a prompt. + - `class ProgrammaticToolCalling` + - `class ImageGeneration` A tool that generates images using the GPT image models. @@ -58560,9 +65167,32 @@ puts(compacted_response) Used by OpenAI to cache responses for similar requests to optimize your cache hit rates. Replaces the `user` field. [Learn more](https://platform.openai.com/docs/guides/prompt-caching). + - `prompt_cache_options: PromptCacheOptions{ mode, ttl}` + + The prompt-caching options that were applied to the response. Supported for `gpt-5.6` and later models. + + - `mode: :implicit | :explicit` + + Whether implicit prompt-cache breakpoints were enabled. + + - `:implicit` + + - `:explicit` + + - `ttl: :"30m"` + + The minimum lifetime applied to each cache breakpoint. + + - `:"30m"` + - `prompt_cache_retention: :in_memory | :"24h"` + Deprecated. Use `prompt_cache_options.ttl` instead. + The retention policy for the prompt cache. Set to `24h` to enable extended prompt caching, which keeps cached prefixes active for longer, up to a maximum of 24 hours. [Learn more](https://platform.openai.com/docs/guides/prompt-caching#prompt-cache-retention). + This field expresses a maximum retention policy, while + `prompt_cache_options.ttl` expresses a minimum cache lifetime. The two + fields are independent and do not interact. For `gpt-5.5`, `gpt-5.5-pro`, and future models, only `24h` is supported. For older models that support both `in_memory` and `24h`, the default depends on your organization's data retention policy: @@ -58595,16 +65225,13 @@ puts(compacted_response) - `effort: ReasoningEffort` - Constrains effort on reasoning for - [reasoning models](https://platform.openai.com/docs/guides/reasoning). - Currently supported values are `none`, `minimal`, `low`, `medium`, `high`, and `xhigh`. Reducing - reasoning effort can result in faster responses and fewer tokens used - on reasoning in a response. - - - `gpt-5.1` defaults to `none`, which does not perform reasoning. The supported reasoning values for `gpt-5.1` are `none`, `low`, `medium`, and `high`. Tool calls are supported for all reasoning values in gpt-5.1. - - All models before `gpt-5.1` default to `medium` reasoning effort, and do not support `none`. - - The `gpt-5-pro` model defaults to (and only supports) `high` reasoning effort. - - `xhigh` is supported for all models after `gpt-5.1-codex-max`. + Constrains effort on reasoning for reasoning models. Currently supported + values are `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max`. + Reducing reasoning effort can result in faster responses and fewer tokens + used on reasoning in a response. Not all reasoning models support every + value. See the + [reasoning guide](https://platform.openai.com/docs/guides/reasoning) + for model-specific support. - `:none` @@ -58618,6 +65245,8 @@ puts(compacted_response) - `:xhigh` + - `:max` + - `generate_summary: :auto | :concise | :detailed` **Deprecated:** use `summary` instead. @@ -58632,6 +65261,24 @@ puts(compacted_response) - `:detailed` + - `mode: String | :standard | :pro` + + Controls the reasoning execution mode for the request. + + When returned on a response, this is the effective execution mode. + + - `String = String` + + - `Mode = :standard | :pro` + + Controls the reasoning execution mode for the request. + + When returned on a response, this is the effective execution mode. + + - `:standard` + + - `:pro` + - `summary: :auto | :concise | :detailed` A summary of the reasoning performed by the model. This can be @@ -58812,10 +65459,14 @@ puts(compacted_response) The number of input tokens. - - `input_tokens_details: InputTokensDetails{ cached_tokens}` + - `input_tokens_details: InputTokensDetails{ cache_write_tokens, cached_tokens}` A detailed breakdown of the input tokens. + - `cache_write_tokens: Integer` + + The number of input tokens that were written to the cache. + - `cached_tokens: Integer` The number of tokens that were retrieved from the cache. @@ -58906,7 +65557,7 @@ puts(compacted_response) An error object returned when the model fails to generate a Response. - - `code: :server_error | :rate_limit_exceeded | :invalid_prompt | 15 more` + - `code: :server_error | :rate_limit_exceeded | :invalid_prompt | 16 more` The error code for the response. @@ -58916,6 +65567,8 @@ puts(compacted_response) - `:invalid_prompt` + - `:bio_policy` + - `:vector_store_timeout` - `:invalid_image` @@ -59016,6 +65669,16 @@ puts(compacted_response) - `:input_text` + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + + 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`. + + - `:explicit` + - `class ResponseInputImage` An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). @@ -59046,6 +65709,16 @@ puts(compacted_response) The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + + 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`. + + - `:explicit` + - `class ResponseInputFile` A file input to the model. @@ -59056,9 +65729,11 @@ puts(compacted_response) - `:input_file` - - `detail: :low | :high` + - `detail: :auto | :low | :high` - The detail level of the file to be sent to the model. Use `low` for the default rendering behavior, or `high` to render the file at higher quality. Defaults to `low`. + The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. + + - `:auto` - `:low` @@ -59080,6 +65755,16 @@ puts(compacted_response) The name of the file to be sent to the model. + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + + 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`. + + - `:explicit` + - `role: :user | :assistant | :system | :developer` The role of the message input. One of `user`, `assistant`, `system`, or @@ -60027,6 +66712,26 @@ puts(compacted_response) The unique ID of the function tool call. + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + - `:program` + - `namespace: String` The namespace of the function to run. @@ -60076,6 +66781,16 @@ puts(compacted_response) - `:input_text` + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + + 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`. + + - `:explicit` + - `class ResponseInputImageContent` An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) @@ -60106,6 +66821,16 @@ puts(compacted_response) The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + + 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`. + + - `:explicit` + - `class ResponseInputFileContent` A file input to the model. @@ -60116,9 +66841,11 @@ puts(compacted_response) - `:input_file` - - `detail: :low | :high` + - `detail: :auto | :low | :high` + + The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. - The detail level of the file to be sent to the model. Use `low` for the default rendering behavior, or `high` to render the file at higher quality. Defaults to `low`. + - `:auto` - `:low` @@ -60140,6 +66867,16 @@ puts(compacted_response) The name of the file to be sent to the model. + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + + 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`. + + - `:explicit` + - `type: :function_call_output` The type of the function tool call output. Always `function_call_output`. @@ -60150,6 +66887,30 @@ puts(compacted_response) The unique ID of the function tool call output. Populated when this item is returned via API. + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + The caller type. Always `direct`. + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + The caller type. Always `program`. + + - `:program` + - `status: :in_progress | :completed | :incomplete` The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. @@ -60218,7 +66979,7 @@ puts(compacted_response) - `strict: bool` - Whether to enforce strict parameter validation. Default `true`. + Whether strict parameter validation is enforced for this function tool. - `type: :function` @@ -60226,6 +66987,14 @@ puts(compacted_response) - `:function` + - `allowed_callers: Array[:direct | :programmatic]` + + The tool invocation context(s). + + - `:direct` + + - `:programmatic` + - `defer_loading: bool` Whether this function is deferred and loaded via tool search. @@ -60234,6 +67003,10 @@ puts(compacted_response) A description of the function. Used by the model to determine whether or not to call the function. + - `output_schema: Hash[Symbol, untyped]` + + A JSON schema object describing the JSON value encoded in string outputs for this function. + - `class FileSearchTool` A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). @@ -60289,7 +67062,7 @@ puts(compacted_response) - `:nin` - - `value: String | Float | bool | Array[String | Float]` + - `value: String | Float | bool | Array[untyped]` The value to compare against the attribute key; supports string, number, or boolean types. @@ -60299,11 +67072,7 @@ puts(compacted_response) - `UnionMember2 = bool` - - `UnionMember3 = Array[String | Float]` - - - `String = String` - - - `Float = Float` + - `UnionMember3 = Array[untyped]` - `class CompoundFilter` @@ -60476,6 +67245,14 @@ puts(compacted_response) - `:mcp` + - `allowed_callers: Array[:direct | :programmatic]` + + The tool invocation context(s). + + - `:direct` + + - `:programmatic` + - `allowed_tools: Array[String] | McpToolFilter{ read_only, tool_names}` List of allowed tool names or a filter object. @@ -60694,6 +67471,22 @@ puts(compacted_response) - `:code_interpreter` + - `allowed_callers: Array[:direct | :programmatic]` + + The tool invocation context(s). + + - `:direct` + + - `:programmatic` + + - `class ProgrammaticToolCalling` + + - `type: :programmatic_tool_calling` + + The type of the tool. Always `programmatic_tool_calling`. + + - `:programmatic_tool_calling` + - `class ImageGeneration` A tool that generates images using the GPT image models. @@ -60857,6 +67650,14 @@ puts(compacted_response) - `:shell` + - `allowed_callers: Array[:direct | :programmatic]` + + The tool invocation context(s). + + - `:direct` + + - `:programmatic` + - `environment: ContainerAuto | LocalEnvironment | ContainerReference` - `class ContainerAuto` @@ -60997,6 +67798,14 @@ puts(compacted_response) - `:custom` + - `allowed_callers: Array[:direct | :programmatic]` + + The tool invocation context(s). + + - `:direct` + + - `:programmatic` + - `defer_loading: bool` Whether this tool should be deferred and discovered via tool search. @@ -61053,7 +67862,7 @@ puts(compacted_response) The namespace name used in tool calls (for example, `crm`). - - `tools: Array[Function{ name, type, defer_loading, 3 more} | CustomTool]` + - `tools: Array[Function{ name, type, allowed_callers, 5 more} | CustomTool]` The function/custom tools available inside this namespace. @@ -61065,16 +67874,30 @@ puts(compacted_response) - `:function` + - `allowed_callers: Array[:direct | :programmatic]` + + The tool invocation context(s). + + - `:direct` + + - `:programmatic` + - `defer_loading: bool` Whether this function should be deferred and discovered via tool search. - `description: String` + - `output_schema: Hash[Symbol, untyped]` + + A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. + - `parameters: untyped` - `strict: bool` + Whether to enforce strict parameter validation. If omitted, Responses attempts to use strict validation when the schema is compatible, and falls back to non-strict validation otherwise. + - `class CustomTool` A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) @@ -61175,6 +67998,14 @@ puts(compacted_response) - `:apply_patch` + - `allowed_callers: Array[:direct | :programmatic]` + + The tool invocation context(s). + + - `:direct` + + - `:programmatic` + - `type: :tool_search_output` The item type. Always `tool_search_output`. @@ -61249,6 +68080,8 @@ puts(compacted_response) A tool that runs Python code to help generate a response to a prompt. + - `class ProgrammaticToolCalling` + - `class ImageGeneration` A tool that generates images using the GPT image models. @@ -61589,6 +68422,30 @@ puts(compacted_response) The unique ID of the shell tool call. Populated when this item is returned via API. + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + The caller type. Always `direct`. + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + The caller type. Always `program`. + + - `:program` + - `environment: LocalEnvironment | ContainerReference` The environment to execute the shell commands in. @@ -61665,6 +68522,30 @@ puts(compacted_response) The unique ID of the shell tool call output. Populated when this item is returned via API. + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + The caller type. Always `direct`. + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + The caller type. Always `program`. + + - `:program` + - `max_output_length: Integer` The maximum number of UTF-8 characters captured for this shell call's combined output. @@ -61759,6 +68640,30 @@ puts(compacted_response) The unique ID of the apply patch tool call. Populated when this item is returned via API. + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + The caller type. Always `direct`. + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + The caller type. Always `program`. + + - `:program` + - `class ApplyPatchCallOutput` The streamed output emitted by an apply patch tool call. @@ -61785,6 +68690,30 @@ puts(compacted_response) The unique ID of the apply patch tool call output. Populated when this item is returned via API. + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + The caller type. Always `direct`. + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + The caller type. Always `program`. + + - `:program` + - `output: String` Optional human-readable log text from the apply patch tool (e.g., patch results or errors). @@ -61979,6 +68908,30 @@ puts(compacted_response) The unique ID of the custom tool call output in the OpenAI platform. + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + The caller type. Always `direct`. + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + The caller type. Always `program`. + + - `:program` + - `class ResponseCustomToolCall` A call to a custom tool created by the model. @@ -62005,6 +68958,26 @@ puts(compacted_response) The unique ID of the custom tool call in the OpenAI platform. + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + - `:program` + - `namespace: String` The namespace of the custom tool being called. @@ -62033,6 +69006,58 @@ puts(compacted_response) - `:item_reference` + - `class Program` + + - `id: String` + + The unique ID of this program item. + + - `call_id: String` + + The stable call ID of the program item. + + - `code: String` + + The JavaScript source executed by programmatic tool calling. + + - `fingerprint: String` + + Opaque program replay fingerprint that must be round-tripped. + + - `type: :program` + + The item type. Always `program`. + + - `:program` + + - `class ProgramOutput` + + - `id: String` + + The unique ID of this program output item. + + - `call_id: String` + + The call ID of the program item. + + - `result: String` + + The result produced by the program item. + + - `status: :completed | :incomplete` + + The terminal status of the program output. + + - `:completed` + + - `:incomplete` + + - `type: :program_output` + + The item type. Always `program_output`. + + - `:program_output` + - `metadata: Metadata` Set of 16 key-value pairs that can be attached to an object. This can be @@ -62051,7 +69076,13 @@ puts(compacted_response) - `String = String` - - `ChatModel = :"gpt-5.4" | :"gpt-5.4-mini" | :"gpt-5.4-nano" | 75 more` + - `ChatModel = :"gpt-5.6-sol" | :"gpt-5.6-terra" | :"gpt-5.6-luna" | 78 more` + + - `:"gpt-5.6-sol"` + + - `:"gpt-5.6-terra"` + + - `:"gpt-5.6-luna"` - `:"gpt-5.4"` @@ -62322,6 +69353,30 @@ puts(compacted_response) - `:function_call_output` + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + The caller type. Always `direct`. + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + The caller type. Always `program`. + + - `:program` + - `created_by: String` The identifier of the actor that created the item. @@ -62397,6 +69452,58 @@ puts(compacted_response) for subsequent turns of a conversation if you are manually [managing context](https://platform.openai.com/docs/guides/conversation-state). + - `class Program` + + - `id: String` + + The unique ID of the program item. + + - `call_id: String` + + The stable call ID of the program item. + + - `code: String` + + The JavaScript source executed by programmatic tool calling. + + - `fingerprint: String` + + Opaque program replay fingerprint that must be round-tripped. + + - `type: :program` + + The type of the item. Always `program`. + + - `:program` + + - `class ProgramOutput` + + - `id: String` + + The unique ID of the program output item. + + - `call_id: String` + + The call ID of the program item. + + - `result: String` + + The result produced by the program item. + + - `status: :completed | :incomplete` + + The terminal status of the program output item. + + - `:completed` + + - `:incomplete` + + - `type: :program_output` + + The type of the item. Always `program_output`. + + - `:program_output` + - `class ResponseToolSearchCall` - `id: String` @@ -62501,6 +69608,8 @@ puts(compacted_response) A tool that runs Python code to help generate a response to a prompt. + - `class ProgrammaticToolCalling` + - `class ImageGeneration` A tool that generates images using the GPT image models. @@ -62603,6 +69712,8 @@ puts(compacted_response) A tool that runs Python code to help generate a response to a prompt. + - `class ProgrammaticToolCalling` + - `class ImageGeneration` A tool that generates images using the GPT image models. @@ -62851,6 +69962,26 @@ puts(compacted_response) - `:shell_call` + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + - `:program` + - `created_by: String` The ID of the entity that created this tool call. @@ -62931,6 +70062,26 @@ puts(compacted_response) - `:shell_call_output` + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + - `:program` + - `created_by: String` The identifier of the actor that created the item. @@ -63015,6 +70166,26 @@ puts(compacted_response) - `:apply_patch_call` + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + - `:program` + - `created_by: String` The ID of the entity that created this tool call. @@ -63045,6 +70216,26 @@ puts(compacted_response) - `:apply_patch_call_output` + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + - `:program` + - `created_by: String` The ID of the entity that created this tool call output. @@ -63236,7 +70427,7 @@ puts(compacted_response) What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. We generally recommend altering this or `top_p` but not both. - - `tool_choice: ToolChoiceOptions | ToolChoiceAllowed | ToolChoiceTypes | 5 more` + - `tool_choice: ToolChoiceOptions | ToolChoiceAllowed | ToolChoiceTypes | 6 more` How the model should select which tool (or tools) to use when generating a response. See the `tools` parameter to see how to specify which tools @@ -63378,6 +70569,14 @@ puts(compacted_response) - `:custom` + - `class SpecificProgrammaticToolCallingParam` + + - `type: :programmatic_tool_calling` + + The tool to call. Always `programmatic_tool_calling`. + + - `:programmatic_tool_calling` + - `class ToolChoiceApplyPatch` Forces the model to call the apply_patch tool when executing a tool call. @@ -63448,6 +70647,8 @@ puts(compacted_response) A tool that runs Python code to help generate a response to a prompt. + - `class ProgrammaticToolCalling` + - `class ImageGeneration` A tool that generates images using the GPT image models. @@ -63674,9 +70875,32 @@ puts(compacted_response) Used by OpenAI to cache responses for similar requests to optimize your cache hit rates. Replaces the `user` field. [Learn more](https://platform.openai.com/docs/guides/prompt-caching). + - `prompt_cache_options: PromptCacheOptions{ mode, ttl}` + + The prompt-caching options that were applied to the response. Supported for `gpt-5.6` and later models. + + - `mode: :implicit | :explicit` + + Whether implicit prompt-cache breakpoints were enabled. + + - `:implicit` + + - `:explicit` + + - `ttl: :"30m"` + + The minimum lifetime applied to each cache breakpoint. + + - `:"30m"` + - `prompt_cache_retention: :in_memory | :"24h"` + Deprecated. Use `prompt_cache_options.ttl` instead. + The retention policy for the prompt cache. Set to `24h` to enable extended prompt caching, which keeps cached prefixes active for longer, up to a maximum of 24 hours. [Learn more](https://platform.openai.com/docs/guides/prompt-caching#prompt-cache-retention). + This field expresses a maximum retention policy, while + `prompt_cache_options.ttl` expresses a minimum cache lifetime. The two + fields are independent and do not interact. For `gpt-5.5`, `gpt-5.5-pro`, and future models, only `24h` is supported. For older models that support both `in_memory` and `24h`, the default depends on your organization's data retention policy: @@ -63709,16 +70933,13 @@ puts(compacted_response) - `effort: ReasoningEffort` - Constrains effort on reasoning for - [reasoning models](https://platform.openai.com/docs/guides/reasoning). - Currently supported values are `none`, `minimal`, `low`, `medium`, `high`, and `xhigh`. Reducing - reasoning effort can result in faster responses and fewer tokens used - on reasoning in a response. - - - `gpt-5.1` defaults to `none`, which does not perform reasoning. The supported reasoning values for `gpt-5.1` are `none`, `low`, `medium`, and `high`. Tool calls are supported for all reasoning values in gpt-5.1. - - All models before `gpt-5.1` default to `medium` reasoning effort, and do not support `none`. - - The `gpt-5-pro` model defaults to (and only supports) `high` reasoning effort. - - `xhigh` is supported for all models after `gpt-5.1-codex-max`. + Constrains effort on reasoning for reasoning models. Currently supported + values are `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max`. + Reducing reasoning effort can result in faster responses and fewer tokens + used on reasoning in a response. Not all reasoning models support every + value. See the + [reasoning guide](https://platform.openai.com/docs/guides/reasoning) + for model-specific support. - `:none` @@ -63732,6 +70953,8 @@ puts(compacted_response) - `:xhigh` + - `:max` + - `generate_summary: :auto | :concise | :detailed` **Deprecated:** use `summary` instead. @@ -63746,6 +70969,24 @@ puts(compacted_response) - `:detailed` + - `mode: String | :standard | :pro` + + Controls the reasoning execution mode for the request. + + When returned on a response, this is the effective execution mode. + + - `String = String` + + - `Mode = :standard | :pro` + + Controls the reasoning execution mode for the request. + + When returned on a response, this is the effective execution mode. + + - `:standard` + + - `:pro` + - `summary: :auto | :concise | :detailed` A summary of the reasoning performed by the model. This can be @@ -63926,10 +71167,14 @@ puts(compacted_response) The number of input tokens. - - `input_tokens_details: InputTokensDetails{ cached_tokens}` + - `input_tokens_details: InputTokensDetails{ cache_write_tokens, cached_tokens}` A detailed breakdown of the input tokens. + - `cache_write_tokens: Integer` + + The number of input tokens that were written to the cache. + - `cached_tokens: Integer` The number of tokens that were retrieved from the cache. @@ -64010,6 +71255,16 @@ puts(compacted_response) - `:input_text` + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + + 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`. + + - `:explicit` + - `class ResponseInputImage` An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). @@ -64040,6 +71295,16 @@ puts(compacted_response) The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + + 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`. + + - `:explicit` + - `class ResponseInputFile` A file input to the model. @@ -64050,9 +71315,11 @@ puts(compacted_response) - `:input_file` - - `detail: :low | :high` + - `detail: :auto | :low | :high` - The detail level of the file to be sent to the model. Use `low` for the default rendering behavior, or `high` to render the file at higher quality. Defaults to `low`. + The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. + + - `:auto` - `:low` @@ -64074,6 +71341,16 @@ puts(compacted_response) The name of the file to be sent to the model. + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + + 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`. + + - `:explicit` + - `role: :user | :assistant | :system | :developer` The role of the message input. One of `user`, `assistant`, `system`, or @@ -65021,6 +72298,26 @@ puts(compacted_response) The unique ID of the function tool call. + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + - `:program` + - `namespace: String` The namespace of the function to run. @@ -65070,6 +72367,16 @@ puts(compacted_response) - `:input_text` + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + + 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`. + + - `:explicit` + - `class ResponseInputImageContent` An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) @@ -65100,6 +72407,16 @@ puts(compacted_response) The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + + 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`. + + - `:explicit` + - `class ResponseInputFileContent` A file input to the model. @@ -65110,9 +72427,11 @@ puts(compacted_response) - `:input_file` - - `detail: :low | :high` + - `detail: :auto | :low | :high` + + The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. - The detail level of the file to be sent to the model. Use `low` for the default rendering behavior, or `high` to render the file at higher quality. Defaults to `low`. + - `:auto` - `:low` @@ -65134,6 +72453,16 @@ puts(compacted_response) The name of the file to be sent to the model. + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + + 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`. + + - `:explicit` + - `type: :function_call_output` The type of the function tool call output. Always `function_call_output`. @@ -65144,6 +72473,30 @@ puts(compacted_response) The unique ID of the function tool call output. Populated when this item is returned via API. + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + The caller type. Always `direct`. + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + The caller type. Always `program`. + + - `:program` + - `status: :in_progress | :completed | :incomplete` The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. @@ -65212,7 +72565,7 @@ puts(compacted_response) - `strict: bool` - Whether to enforce strict parameter validation. Default `true`. + Whether strict parameter validation is enforced for this function tool. - `type: :function` @@ -65220,6 +72573,14 @@ puts(compacted_response) - `:function` + - `allowed_callers: Array[:direct | :programmatic]` + + The tool invocation context(s). + + - `:direct` + + - `:programmatic` + - `defer_loading: bool` Whether this function is deferred and loaded via tool search. @@ -65228,6 +72589,10 @@ puts(compacted_response) A description of the function. Used by the model to determine whether or not to call the function. + - `output_schema: Hash[Symbol, untyped]` + + A JSON schema object describing the JSON value encoded in string outputs for this function. + - `class FileSearchTool` A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). @@ -65283,7 +72648,7 @@ puts(compacted_response) - `:nin` - - `value: String | Float | bool | Array[String | Float]` + - `value: String | Float | bool | Array[untyped]` The value to compare against the attribute key; supports string, number, or boolean types. @@ -65293,11 +72658,7 @@ puts(compacted_response) - `UnionMember2 = bool` - - `UnionMember3 = Array[String | Float]` - - - `String = String` - - - `Float = Float` + - `UnionMember3 = Array[untyped]` - `class CompoundFilter` @@ -65470,6 +72831,14 @@ puts(compacted_response) - `:mcp` + - `allowed_callers: Array[:direct | :programmatic]` + + The tool invocation context(s). + + - `:direct` + + - `:programmatic` + - `allowed_tools: Array[String] | McpToolFilter{ read_only, tool_names}` List of allowed tool names or a filter object. @@ -65688,6 +73057,22 @@ puts(compacted_response) - `:code_interpreter` + - `allowed_callers: Array[:direct | :programmatic]` + + The tool invocation context(s). + + - `:direct` + + - `:programmatic` + + - `class ProgrammaticToolCalling` + + - `type: :programmatic_tool_calling` + + The type of the tool. Always `programmatic_tool_calling`. + + - `:programmatic_tool_calling` + - `class ImageGeneration` A tool that generates images using the GPT image models. @@ -65851,6 +73236,14 @@ puts(compacted_response) - `:shell` + - `allowed_callers: Array[:direct | :programmatic]` + + The tool invocation context(s). + + - `:direct` + + - `:programmatic` + - `environment: ContainerAuto | LocalEnvironment | ContainerReference` - `class ContainerAuto` @@ -65991,6 +73384,14 @@ puts(compacted_response) - `:custom` + - `allowed_callers: Array[:direct | :programmatic]` + + The tool invocation context(s). + + - `:direct` + + - `:programmatic` + - `defer_loading: bool` Whether this tool should be deferred and discovered via tool search. @@ -66047,7 +73448,7 @@ puts(compacted_response) The namespace name used in tool calls (for example, `crm`). - - `tools: Array[Function{ name, type, defer_loading, 3 more} | CustomTool]` + - `tools: Array[Function{ name, type, allowed_callers, 5 more} | CustomTool]` The function/custom tools available inside this namespace. @@ -66059,16 +73460,30 @@ puts(compacted_response) - `:function` + - `allowed_callers: Array[:direct | :programmatic]` + + The tool invocation context(s). + + - `:direct` + + - `:programmatic` + - `defer_loading: bool` Whether this function should be deferred and discovered via tool search. - `description: String` + - `output_schema: Hash[Symbol, untyped]` + + A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. + - `parameters: untyped` - `strict: bool` + Whether to enforce strict parameter validation. If omitted, Responses attempts to use strict validation when the schema is compatible, and falls back to non-strict validation otherwise. + - `class CustomTool` A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) @@ -66169,6 +73584,14 @@ puts(compacted_response) - `:apply_patch` + - `allowed_callers: Array[:direct | :programmatic]` + + The tool invocation context(s). + + - `:direct` + + - `:programmatic` + - `type: :tool_search_output` The item type. Always `tool_search_output`. @@ -66243,6 +73666,8 @@ puts(compacted_response) A tool that runs Python code to help generate a response to a prompt. + - `class ProgrammaticToolCalling` + - `class ImageGeneration` A tool that generates images using the GPT image models. @@ -66583,6 +74008,30 @@ puts(compacted_response) The unique ID of the shell tool call. Populated when this item is returned via API. + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + The caller type. Always `direct`. + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + The caller type. Always `program`. + + - `:program` + - `environment: LocalEnvironment | ContainerReference` The environment to execute the shell commands in. @@ -66659,6 +74108,30 @@ puts(compacted_response) The unique ID of the shell tool call output. Populated when this item is returned via API. + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + The caller type. Always `direct`. + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + The caller type. Always `program`. + + - `:program` + - `max_output_length: Integer` The maximum number of UTF-8 characters captured for this shell call's combined output. @@ -66753,6 +74226,30 @@ puts(compacted_response) The unique ID of the apply patch tool call. Populated when this item is returned via API. + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + The caller type. Always `direct`. + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + The caller type. Always `program`. + + - `:program` + - `class ApplyPatchCallOutput` The streamed output emitted by an apply patch tool call. @@ -66779,6 +74276,30 @@ puts(compacted_response) The unique ID of the apply patch tool call output. Populated when this item is returned via API. + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + The caller type. Always `direct`. + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + The caller type. Always `program`. + + - `:program` + - `output: String` Optional human-readable log text from the apply patch tool (e.g., patch results or errors). @@ -66973,6 +74494,30 @@ puts(compacted_response) The unique ID of the custom tool call output in the OpenAI platform. + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + The caller type. Always `direct`. + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + The caller type. Always `program`. + + - `:program` + - `class ResponseCustomToolCall` A call to a custom tool created by the model. @@ -66999,6 +74544,26 @@ puts(compacted_response) The unique ID of the custom tool call in the OpenAI platform. + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + - `:program` + - `namespace: String` The namespace of the custom tool being called. @@ -67027,6 +74592,58 @@ puts(compacted_response) - `:item_reference` + - `class Program` + + - `id: String` + + The unique ID of this program item. + + - `call_id: String` + + The stable call ID of the program item. + + - `code: String` + + The JavaScript source executed by programmatic tool calling. + + - `fingerprint: String` + + Opaque program replay fingerprint that must be round-tripped. + + - `type: :program` + + The item type. Always `program`. + + - `:program` + + - `class ProgramOutput` + + - `id: String` + + The unique ID of this program output item. + + - `call_id: String` + + The call ID of the program item. + + - `result: String` + + The result produced by the program item. + + - `status: :completed | :incomplete` + + The terminal status of the program output. + + - `:completed` + + - `:incomplete` + + - `type: :program_output` + + The item type. Always `program_output`. + + - `:program_output` + ### Response Input Audio - `class ResponseInputAudio` @@ -67074,6 +74691,16 @@ puts(compacted_response) - `:input_text` + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + + 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`. + + - `:explicit` + - `class ResponseInputImage` An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). @@ -67104,6 +74731,16 @@ puts(compacted_response) The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + + 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`. + + - `:explicit` + - `class ResponseInputFile` A file input to the model. @@ -67114,9 +74751,11 @@ puts(compacted_response) - `:input_file` - - `detail: :low | :high` + - `detail: :auto | :low | :high` + + The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. - The detail level of the file to be sent to the model. Use `low` for the default rendering behavior, or `high` to render the file at higher quality. Defaults to `low`. + - `:auto` - `:low` @@ -67138,6 +74777,16 @@ puts(compacted_response) The name of the file to be sent to the model. + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + + 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`. + + - `:explicit` + ### Response Input File - `class ResponseInputFile` @@ -67150,9 +74799,11 @@ puts(compacted_response) - `:input_file` - - `detail: :low | :high` + - `detail: :auto | :low | :high` - The detail level of the file to be sent to the model. Use `low` for the default rendering behavior, or `high` to render the file at higher quality. Defaults to `low`. + The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. + + - `:auto` - `:low` @@ -67174,6 +74825,16 @@ puts(compacted_response) The name of the file to be sent to the model. + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + + 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`. + + - `:explicit` + ### Response Input File Content - `class ResponseInputFileContent` @@ -67186,9 +74847,11 @@ puts(compacted_response) - `:input_file` - - `detail: :low | :high` + - `detail: :auto | :low | :high` + + The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. - The detail level of the file to be sent to the model. Use `low` for the default rendering behavior, or `high` to render the file at higher quality. Defaults to `low`. + - `:auto` - `:low` @@ -67210,6 +74873,16 @@ puts(compacted_response) The name of the file to be sent to the model. + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + + 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`. + + - `:explicit` + ### Response Input Image - `class ResponseInputImage` @@ -67242,6 +74915,16 @@ puts(compacted_response) The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + + 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`. + + - `:explicit` + ### Response Input Image Content - `class ResponseInputImageContent` @@ -67274,9 +74957,19 @@ puts(compacted_response) The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + + 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`. + + - `:explicit` + ### Response Input Item -- `ResponseInputItem = EasyInputMessage | Message{ content, role, status, type} | ResponseOutputMessage | 27 more` +- `ResponseInputItem = EasyInputMessage | Message{ content, role, status, type} | ResponseOutputMessage | 29 more` A message input to the model with a role indicating instruction following hierarchy. Instructions given with the `developer` or `system` role take @@ -67320,6 +75013,16 @@ puts(compacted_response) - `:input_text` + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + + 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`. + + - `:explicit` + - `class ResponseInputImage` An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). @@ -67350,6 +75053,16 @@ puts(compacted_response) The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + + 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`. + + - `:explicit` + - `class ResponseInputFile` A file input to the model. @@ -67360,9 +75073,11 @@ puts(compacted_response) - `:input_file` - - `detail: :low | :high` + - `detail: :auto | :low | :high` - The detail level of the file to be sent to the model. Use `low` for the default rendering behavior, or `high` to render the file at higher quality. Defaults to `low`. + The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. + + - `:auto` - `:low` @@ -67384,6 +75099,16 @@ puts(compacted_response) The name of the file to be sent to the model. + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + + 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`. + + - `:explicit` + - `role: :user | :assistant | :system | :developer` The role of the message input. One of `user`, `assistant`, `system`, or @@ -68331,6 +76056,26 @@ puts(compacted_response) The unique ID of the function tool call. + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + - `:program` + - `namespace: String` The namespace of the function to run. @@ -68380,6 +76125,16 @@ puts(compacted_response) - `:input_text` + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + + 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`. + + - `:explicit` + - `class ResponseInputImageContent` An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) @@ -68410,6 +76165,16 @@ puts(compacted_response) The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + + 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`. + + - `:explicit` + - `class ResponseInputFileContent` A file input to the model. @@ -68420,9 +76185,11 @@ puts(compacted_response) - `:input_file` - - `detail: :low | :high` + - `detail: :auto | :low | :high` + + The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. - The detail level of the file to be sent to the model. Use `low` for the default rendering behavior, or `high` to render the file at higher quality. Defaults to `low`. + - `:auto` - `:low` @@ -68444,6 +76211,16 @@ puts(compacted_response) The name of the file to be sent to the model. + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + + 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`. + + - `:explicit` + - `type: :function_call_output` The type of the function tool call output. Always `function_call_output`. @@ -68454,6 +76231,30 @@ puts(compacted_response) The unique ID of the function tool call output. Populated when this item is returned via API. + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + The caller type. Always `direct`. + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + The caller type. Always `program`. + + - `:program` + - `status: :in_progress | :completed | :incomplete` The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. @@ -68522,7 +76323,7 @@ puts(compacted_response) - `strict: bool` - Whether to enforce strict parameter validation. Default `true`. + Whether strict parameter validation is enforced for this function tool. - `type: :function` @@ -68530,6 +76331,14 @@ puts(compacted_response) - `:function` + - `allowed_callers: Array[:direct | :programmatic]` + + The tool invocation context(s). + + - `:direct` + + - `:programmatic` + - `defer_loading: bool` Whether this function is deferred and loaded via tool search. @@ -68538,6 +76347,10 @@ puts(compacted_response) A description of the function. Used by the model to determine whether or not to call the function. + - `output_schema: Hash[Symbol, untyped]` + + A JSON schema object describing the JSON value encoded in string outputs for this function. + - `class FileSearchTool` A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). @@ -68593,7 +76406,7 @@ puts(compacted_response) - `:nin` - - `value: String | Float | bool | Array[String | Float]` + - `value: String | Float | bool | Array[untyped]` The value to compare against the attribute key; supports string, number, or boolean types. @@ -68603,11 +76416,7 @@ puts(compacted_response) - `UnionMember2 = bool` - - `UnionMember3 = Array[String | Float]` - - - `String = String` - - - `Float = Float` + - `UnionMember3 = Array[untyped]` - `class CompoundFilter` @@ -68780,6 +76589,14 @@ puts(compacted_response) - `:mcp` + - `allowed_callers: Array[:direct | :programmatic]` + + The tool invocation context(s). + + - `:direct` + + - `:programmatic` + - `allowed_tools: Array[String] | McpToolFilter{ read_only, tool_names}` List of allowed tool names or a filter object. @@ -68998,6 +76815,22 @@ puts(compacted_response) - `:code_interpreter` + - `allowed_callers: Array[:direct | :programmatic]` + + The tool invocation context(s). + + - `:direct` + + - `:programmatic` + + - `class ProgrammaticToolCalling` + + - `type: :programmatic_tool_calling` + + The type of the tool. Always `programmatic_tool_calling`. + + - `:programmatic_tool_calling` + - `class ImageGeneration` A tool that generates images using the GPT image models. @@ -69161,6 +76994,14 @@ puts(compacted_response) - `:shell` + - `allowed_callers: Array[:direct | :programmatic]` + + The tool invocation context(s). + + - `:direct` + + - `:programmatic` + - `environment: ContainerAuto | LocalEnvironment | ContainerReference` - `class ContainerAuto` @@ -69301,6 +77142,14 @@ puts(compacted_response) - `:custom` + - `allowed_callers: Array[:direct | :programmatic]` + + The tool invocation context(s). + + - `:direct` + + - `:programmatic` + - `defer_loading: bool` Whether this tool should be deferred and discovered via tool search. @@ -69357,7 +77206,7 @@ puts(compacted_response) The namespace name used in tool calls (for example, `crm`). - - `tools: Array[Function{ name, type, defer_loading, 3 more} | CustomTool]` + - `tools: Array[Function{ name, type, allowed_callers, 5 more} | CustomTool]` The function/custom tools available inside this namespace. @@ -69369,16 +77218,30 @@ puts(compacted_response) - `:function` + - `allowed_callers: Array[:direct | :programmatic]` + + The tool invocation context(s). + + - `:direct` + + - `:programmatic` + - `defer_loading: bool` Whether this function should be deferred and discovered via tool search. - `description: String` + - `output_schema: Hash[Symbol, untyped]` + + A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. + - `parameters: untyped` - `strict: bool` + Whether to enforce strict parameter validation. If omitted, Responses attempts to use strict validation when the schema is compatible, and falls back to non-strict validation otherwise. + - `class CustomTool` A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) @@ -69479,6 +77342,14 @@ puts(compacted_response) - `:apply_patch` + - `allowed_callers: Array[:direct | :programmatic]` + + The tool invocation context(s). + + - `:direct` + + - `:programmatic` + - `type: :tool_search_output` The item type. Always `tool_search_output`. @@ -69553,6 +77424,8 @@ puts(compacted_response) A tool that runs Python code to help generate a response to a prompt. + - `class ProgrammaticToolCalling` + - `class ImageGeneration` A tool that generates images using the GPT image models. @@ -69893,6 +77766,30 @@ puts(compacted_response) The unique ID of the shell tool call. Populated when this item is returned via API. + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + The caller type. Always `direct`. + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + The caller type. Always `program`. + + - `:program` + - `environment: LocalEnvironment | ContainerReference` The environment to execute the shell commands in. @@ -69969,6 +77866,30 @@ puts(compacted_response) The unique ID of the shell tool call output. Populated when this item is returned via API. + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + The caller type. Always `direct`. + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + The caller type. Always `program`. + + - `:program` + - `max_output_length: Integer` The maximum number of UTF-8 characters captured for this shell call's combined output. @@ -70063,6 +77984,30 @@ puts(compacted_response) The unique ID of the apply patch tool call. Populated when this item is returned via API. + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + The caller type. Always `direct`. + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + The caller type. Always `program`. + + - `:program` + - `class ApplyPatchCallOutput` The streamed output emitted by an apply patch tool call. @@ -70089,6 +78034,30 @@ puts(compacted_response) The unique ID of the apply patch tool call output. Populated when this item is returned via API. + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + The caller type. Always `direct`. + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + The caller type. Always `program`. + + - `:program` + - `output: String` Optional human-readable log text from the apply patch tool (e.g., patch results or errors). @@ -70283,6 +78252,30 @@ puts(compacted_response) The unique ID of the custom tool call output in the OpenAI platform. + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + The caller type. Always `direct`. + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + The caller type. Always `program`. + + - `:program` + - `class ResponseCustomToolCall` A call to a custom tool created by the model. @@ -70309,6 +78302,26 @@ puts(compacted_response) The unique ID of the custom tool call in the OpenAI platform. + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + - `:program` + - `namespace: String` The namespace of the custom tool being called. @@ -70337,100 +78350,61 @@ puts(compacted_response) - `:item_reference` -### Response Input Message Content List - -- `ResponseInputMessageContentList = Array[ResponseInputContent]` - - A list of one or many input items to the model, containing different content - types. - - - `class ResponseInputText` - - A text input to the model. - - - `text: String` - - The text input to the model. - - - `type: :input_text` - - The type of the input item. Always `input_text`. - - - `:input_text` - - - `class ResponseInputImage` - - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - - `detail: :low | :high | :auto | :original` - - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - - - `:low` - - - `:high` - - - `:auto` + - `class Program` - - `:original` - - - `type: :input_image` + - `id: String` - The type of the input item. Always `input_image`. + The unique ID of this program item. - - `:input_image` + - `call_id: String` - - `file_id: String` + The stable call ID of the program item. - The ID of the file to be sent to the model. + - `code: String` - - `image_url: String` + The JavaScript source executed by programmatic tool calling. - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + - `fingerprint: String` - - `class ResponseInputFile` + Opaque program replay fingerprint that must be round-tripped. - A file input to the model. + - `type: :program` - - `type: :input_file` + The item type. Always `program`. - The type of the input item. Always `input_file`. + - `:program` - - `:input_file` + - `class ProgramOutput` - - `detail: :low | :high` - - The detail level of the file to be sent to the model. Use `low` for the default rendering behavior, or `high` to render the file at higher quality. Defaults to `low`. - - - `:low` + - `id: String` - - `:high` + The unique ID of this program output item. - - `file_data: String` + - `call_id: String` - The content of the file to be sent to the model. + The call ID of the program item. - - `file_id: String` + - `result: String` - The ID of the file to be sent to the model. + The result produced by the program item. - - `file_url: String` + - `status: :completed | :incomplete` - The URL of the file to be sent to the model. + The terminal status of the program output. - - `filename: String` + - `:completed` - The name of the file to be sent to the model. + - `:incomplete` -### Response Input Message Item + - `type: :program_output` -- `class ResponseInputMessageItem` + The item type. Always `program_output`. - - `id: String` + - `:program_output` - The unique ID of the message input. +### Response Input Message Content List - - `content: ResponseInputMessageContentList` +- `ResponseInputMessageContentList = Array[ResponseInputContent]` A list of one or many input items to the model, containing different content types. @@ -70449,6 +78423,16 @@ puts(compacted_response) - `:input_text` + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + + 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`. + + - `:explicit` + - `class ResponseInputImage` An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). @@ -70479,6 +78463,16 @@ puts(compacted_response) The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + + 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`. + + - `:explicit` + - `class ResponseInputFile` A file input to the model. @@ -70489,9 +78483,11 @@ puts(compacted_response) - `:input_file` - - `detail: :low | :high` + - `detail: :auto | :low | :high` + + The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. - The detail level of the file to be sent to the model. Use `low` for the default rendering behavior, or `high` to render the file at higher quality. Defaults to `low`. + - `:auto` - `:low` @@ -70513,72 +78509,19 @@ puts(compacted_response) The name of the file to be sent to the model. - - `role: :user | :system | :developer` - - The role of the message input. One of `user`, `system`, or `developer`. - - - `:user` - - - `:system` - - - `:developer` + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` - - `type: :message` + 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. - The type of the message input. Always set to `message`. + - `mode: :explicit` - - `:message` + The breakpoint mode. Always `explicit`. - - `status: :in_progress | :completed | :incomplete` + - `:explicit` - The status of item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. - - - `:in_progress` - - - `:completed` - - - `:incomplete` - -### Response Input Text - -- `class ResponseInputText` - - A text input to the model. - - - `text: String` - - The text input to the model. - - - `type: :input_text` - - The type of the input item. Always `input_text`. - - - `:input_text` - -### Response Input Text Content - -- `class ResponseInputTextContent` - - A text input to the model. - - - `text: String` - - The text input to the model. - - - `type: :input_text` - - The type of the input item. Always `input_text`. - - - `:input_text` - -### Response Item - -- `ResponseItem = ResponseInputMessageItem | ResponseOutputMessage | ResponseFileSearchToolCall | 24 more` - - Content item used to generate a response. +### Response Input Message Item - - `class ResponseInputMessageItem` +- `class ResponseInputMessageItem` - `id: String` @@ -70603,6 +78546,16 @@ puts(compacted_response) - `:input_text` + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + + 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`. + + - `:explicit` + - `class ResponseInputImage` An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). @@ -70633,6 +78586,16 @@ puts(compacted_response) The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + + 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`. + + - `:explicit` + - `class ResponseInputFile` A file input to the model. @@ -70643,9 +78606,11 @@ puts(compacted_response) - `:input_file` - - `detail: :low | :high` + - `detail: :auto | :low | :high` + + The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. - The detail level of the file to be sent to the model. Use `low` for the default rendering behavior, or `high` to render the file at higher quality. Defaults to `low`. + - `:auto` - `:low` @@ -70667,6 +78632,222 @@ puts(compacted_response) The name of the file to be sent to the model. + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + + 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`. + + - `:explicit` + + - `role: :user | :system | :developer` + + The role of the message input. One of `user`, `system`, or `developer`. + + - `:user` + + - `:system` + + - `:developer` + + - `type: :message` + + The type of the message input. Always set to `message`. + + - `:message` + + - `status: :in_progress | :completed | :incomplete` + + The status of item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. + + - `:in_progress` + + - `:completed` + + - `:incomplete` + +### Response Input Text + +- `class ResponseInputText` + + A text input to the model. + + - `text: String` + + The text input to the model. + + - `type: :input_text` + + The type of the input item. Always `input_text`. + + - `:input_text` + + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + + 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`. + + - `:explicit` + +### Response Input Text Content + +- `class ResponseInputTextContent` + + A text input to the model. + + - `text: String` + + The text input to the model. + + - `type: :input_text` + + The type of the input item. Always `input_text`. + + - `:input_text` + + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + + 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`. + + - `:explicit` + +### Response Item + +- `ResponseItem = ResponseInputMessageItem | ResponseOutputMessage | ResponseFileSearchToolCall | 26 more` + + Content item used to generate a response. + + - `class ResponseInputMessageItem` + + - `id: String` + + The unique ID of the message input. + + - `content: ResponseInputMessageContentList` + + A list of one or many input items to the model, containing different content + types. + + - `class ResponseInputText` + + A text input to the model. + + - `text: String` + + The text input to the model. + + - `type: :input_text` + + The type of the input item. Always `input_text`. + + - `:input_text` + + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + + 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`. + + - `:explicit` + + - `class ResponseInputImage` + + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + + - `detail: :low | :high | :auto | :original` + + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + + - `:low` + + - `:high` + + - `:auto` + + - `:original` + + - `type: :input_image` + + The type of the input item. Always `input_image`. + + - `:input_image` + + - `file_id: String` + + The ID of the file to be sent to the model. + + - `image_url: String` + + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + + 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`. + + - `:explicit` + + - `class ResponseInputFile` + + A file input to the model. + + - `type: :input_file` + + The type of the input item. Always `input_file`. + + - `:input_file` + + - `detail: :auto | :low | :high` + + The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. + + - `:auto` + + - `:low` + + - `:high` + + - `file_data: String` + + The content of the file to be sent to the model. + + - `file_id: String` + + The ID of the file to be sent to the model. + + - `file_url: String` + + The URL of the file to be sent to the model. + + - `filename: String` + + The name of the file to be sent to the model. + + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + + 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`. + + - `:explicit` + - `role: :user | :system | :developer` The role of the message input. One of `user`, `system`, or `developer`. @@ -71629,6 +79810,30 @@ puts(compacted_response) - `:function_call_output` + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + The caller type. Always `direct`. + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + The caller type. Always `program`. + + - `:program` + - `created_by: String` The identifier of the actor that created the item. @@ -71721,7 +79926,7 @@ puts(compacted_response) - `strict: bool` - Whether to enforce strict parameter validation. Default `true`. + Whether strict parameter validation is enforced for this function tool. - `type: :function` @@ -71729,6 +79934,14 @@ puts(compacted_response) - `:function` + - `allowed_callers: Array[:direct | :programmatic]` + + The tool invocation context(s). + + - `:direct` + + - `:programmatic` + - `defer_loading: bool` Whether this function is deferred and loaded via tool search. @@ -71737,6 +79950,10 @@ puts(compacted_response) A description of the function. Used by the model to determine whether or not to call the function. + - `output_schema: Hash[Symbol, untyped]` + + A JSON schema object describing the JSON value encoded in string outputs for this function. + - `class FileSearchTool` A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). @@ -71792,7 +80009,7 @@ puts(compacted_response) - `:nin` - - `value: String | Float | bool | Array[String | Float]` + - `value: String | Float | bool | Array[untyped]` The value to compare against the attribute key; supports string, number, or boolean types. @@ -71802,11 +80019,7 @@ puts(compacted_response) - `UnionMember2 = bool` - - `UnionMember3 = Array[String | Float]` - - - `String = String` - - - `Float = Float` + - `UnionMember3 = Array[untyped]` - `class CompoundFilter` @@ -71979,6 +80192,14 @@ puts(compacted_response) - `:mcp` + - `allowed_callers: Array[:direct | :programmatic]` + + The tool invocation context(s). + + - `:direct` + + - `:programmatic` + - `allowed_tools: Array[String] | McpToolFilter{ read_only, tool_names}` List of allowed tool names or a filter object. @@ -72197,6 +80418,22 @@ puts(compacted_response) - `:code_interpreter` + - `allowed_callers: Array[:direct | :programmatic]` + + The tool invocation context(s). + + - `:direct` + + - `:programmatic` + + - `class ProgrammaticToolCalling` + + - `type: :programmatic_tool_calling` + + The type of the tool. Always `programmatic_tool_calling`. + + - `:programmatic_tool_calling` + - `class ImageGeneration` A tool that generates images using the GPT image models. @@ -72360,6 +80597,14 @@ puts(compacted_response) - `:shell` + - `allowed_callers: Array[:direct | :programmatic]` + + The tool invocation context(s). + + - `:direct` + + - `:programmatic` + - `environment: ContainerAuto | LocalEnvironment | ContainerReference` - `class ContainerAuto` @@ -72500,6 +80745,14 @@ puts(compacted_response) - `:custom` + - `allowed_callers: Array[:direct | :programmatic]` + + The tool invocation context(s). + + - `:direct` + + - `:programmatic` + - `defer_loading: bool` Whether this tool should be deferred and discovered via tool search. @@ -72556,7 +80809,7 @@ puts(compacted_response) The namespace name used in tool calls (for example, `crm`). - - `tools: Array[Function{ name, type, defer_loading, 3 more} | CustomTool]` + - `tools: Array[Function{ name, type, allowed_callers, 5 more} | CustomTool]` The function/custom tools available inside this namespace. @@ -72568,16 +80821,30 @@ puts(compacted_response) - `:function` + - `allowed_callers: Array[:direct | :programmatic]` + + The tool invocation context(s). + + - `:direct` + + - `:programmatic` + - `defer_loading: bool` Whether this function should be deferred and discovered via tool search. - `description: String` + - `output_schema: Hash[Symbol, untyped]` + + A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. + - `parameters: untyped` - `strict: bool` + Whether to enforce strict parameter validation. If omitted, Responses attempts to use strict validation when the schema is compatible, and falls back to non-strict validation otherwise. + - `class CustomTool` A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) @@ -72678,6 +80945,14 @@ puts(compacted_response) - `:apply_patch` + - `allowed_callers: Array[:direct | :programmatic]` + + The tool invocation context(s). + + - `:direct` + + - `:programmatic` + - `type: :tool_search_output` The type of the item. Always `tool_search_output`. @@ -72748,6 +81023,8 @@ puts(compacted_response) A tool that runs Python code to help generate a response to a prompt. + - `class ProgrammaticToolCalling` + - `class ImageGeneration` A tool that generates images using the GPT image models. @@ -72847,6 +81124,58 @@ puts(compacted_response) - `:incomplete` + - `class Program` + + - `id: String` + + The unique ID of the program item. + + - `call_id: String` + + The stable call ID of the program item. + + - `code: String` + + The JavaScript source executed by programmatic tool calling. + + - `fingerprint: String` + + Opaque program replay fingerprint that must be round-tripped. + + - `type: :program` + + The type of the item. Always `program`. + + - `:program` + + - `class ProgramOutput` + + - `id: String` + + The unique ID of the program output item. + + - `call_id: String` + + The call ID of the program item. + + - `result: String` + + The result produced by the program item. + + - `status: :completed | :incomplete` + + The terminal status of the program output item. + + - `:completed` + + - `:incomplete` + + - `type: :program_output` + + The type of the item. Always `program_output`. + + - `:program_output` + - `class ResponseCompactionItem` A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). @@ -73122,6 +81451,26 @@ puts(compacted_response) - `:shell_call` + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + - `:program` + - `created_by: String` The ID of the entity that created this tool call. @@ -73202,6 +81551,26 @@ puts(compacted_response) - `:shell_call_output` + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + - `:program` + - `created_by: String` The identifier of the actor that created the item. @@ -73286,6 +81655,26 @@ puts(compacted_response) - `:apply_patch_call` + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + - `:program` + - `created_by: String` The ID of the entity that created this tool call. @@ -73316,6 +81705,26 @@ puts(compacted_response) - `:apply_patch_call_output` + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + - `:program` + - `created_by: String` The ID of the entity that created this tool call output. @@ -73751,7 +82160,7 @@ puts(compacted_response) ### Response Output Item -- `ResponseOutputItem = ResponseOutputMessage | ResponseFileSearchToolCall | ResponseFunctionToolCall | 23 more` +- `ResponseOutputItem = ResponseOutputMessage | ResponseFileSearchToolCall | ResponseFunctionToolCall | 25 more` An output message from the model. @@ -74039,6 +82448,26 @@ puts(compacted_response) The unique ID of the function tool call. + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + - `:program` + - `namespace: String` The namespace of the function to run. @@ -74091,6 +82520,16 @@ puts(compacted_response) - `:input_text` + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + + 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`. + + - `:explicit` + - `class ResponseInputImage` An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). @@ -74121,6 +82560,16 @@ puts(compacted_response) The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + + 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`. + + - `:explicit` + - `class ResponseInputFile` A file input to the model. @@ -74131,9 +82580,11 @@ puts(compacted_response) - `:input_file` - - `detail: :low | :high` + - `detail: :auto | :low | :high` - The detail level of the file to be sent to the model. Use `low` for the default rendering behavior, or `high` to render the file at higher quality. Defaults to `low`. + The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. + + - `:auto` - `:low` @@ -74155,6 +82606,16 @@ puts(compacted_response) The name of the file to be sent to the model. + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + + 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`. + + - `:explicit` + - `status: :in_progress | :completed | :incomplete` The status of the item. One of `in_progress`, `completed`, or @@ -74172,6 +82633,30 @@ puts(compacted_response) - `:function_call_output` + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + The caller type. Always `direct`. + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + The caller type. Always `program`. + + - `:program` + - `created_by: String` The identifier of the actor that created the item. @@ -74839,6 +83324,58 @@ puts(compacted_response) - `:incomplete` + - `class Program` + + - `id: String` + + The unique ID of the program item. + + - `call_id: String` + + The stable call ID of the program item. + + - `code: String` + + The JavaScript source executed by programmatic tool calling. + + - `fingerprint: String` + + Opaque program replay fingerprint that must be round-tripped. + + - `type: :program` + + The type of the item. Always `program`. + + - `:program` + + - `class ProgramOutput` + + - `id: String` + + The unique ID of the program output item. + + - `call_id: String` + + The call ID of the program item. + + - `result: String` + + The result produced by the program item. + + - `status: :completed | :incomplete` + + The terminal status of the program output item. + + - `:completed` + + - `:incomplete` + + - `type: :program_output` + + The type of the item. Always `program_output`. + + - `:program_output` + - `class ResponseToolSearchCall` - `id: String` @@ -74927,7 +83464,7 @@ puts(compacted_response) - `strict: bool` - Whether to enforce strict parameter validation. Default `true`. + Whether strict parameter validation is enforced for this function tool. - `type: :function` @@ -74935,6 +83472,14 @@ puts(compacted_response) - `:function` + - `allowed_callers: Array[:direct | :programmatic]` + + The tool invocation context(s). + + - `:direct` + + - `:programmatic` + - `defer_loading: bool` Whether this function is deferred and loaded via tool search. @@ -74943,6 +83488,10 @@ puts(compacted_response) A description of the function. Used by the model to determine whether or not to call the function. + - `output_schema: Hash[Symbol, untyped]` + + A JSON schema object describing the JSON value encoded in string outputs for this function. + - `class FileSearchTool` A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). @@ -74998,7 +83547,7 @@ puts(compacted_response) - `:nin` - - `value: String | Float | bool | Array[String | Float]` + - `value: String | Float | bool | Array[untyped]` The value to compare against the attribute key; supports string, number, or boolean types. @@ -75008,11 +83557,7 @@ puts(compacted_response) - `UnionMember2 = bool` - - `UnionMember3 = Array[String | Float]` - - - `String = String` - - - `Float = Float` + - `UnionMember3 = Array[untyped]` - `class CompoundFilter` @@ -75185,6 +83730,14 @@ puts(compacted_response) - `:mcp` + - `allowed_callers: Array[:direct | :programmatic]` + + The tool invocation context(s). + + - `:direct` + + - `:programmatic` + - `allowed_tools: Array[String] | McpToolFilter{ read_only, tool_names}` List of allowed tool names or a filter object. @@ -75403,6 +83956,22 @@ puts(compacted_response) - `:code_interpreter` + - `allowed_callers: Array[:direct | :programmatic]` + + The tool invocation context(s). + + - `:direct` + + - `:programmatic` + + - `class ProgrammaticToolCalling` + + - `type: :programmatic_tool_calling` + + The type of the tool. Always `programmatic_tool_calling`. + + - `:programmatic_tool_calling` + - `class ImageGeneration` A tool that generates images using the GPT image models. @@ -75566,6 +84135,14 @@ puts(compacted_response) - `:shell` + - `allowed_callers: Array[:direct | :programmatic]` + + The tool invocation context(s). + + - `:direct` + + - `:programmatic` + - `environment: ContainerAuto | LocalEnvironment | ContainerReference` - `class ContainerAuto` @@ -75706,6 +84283,14 @@ puts(compacted_response) - `:custom` + - `allowed_callers: Array[:direct | :programmatic]` + + The tool invocation context(s). + + - `:direct` + + - `:programmatic` + - `defer_loading: bool` Whether this tool should be deferred and discovered via tool search. @@ -75762,7 +84347,7 @@ puts(compacted_response) The namespace name used in tool calls (for example, `crm`). - - `tools: Array[Function{ name, type, defer_loading, 3 more} | CustomTool]` + - `tools: Array[Function{ name, type, allowed_callers, 5 more} | CustomTool]` The function/custom tools available inside this namespace. @@ -75774,16 +84359,30 @@ puts(compacted_response) - `:function` + - `allowed_callers: Array[:direct | :programmatic]` + + The tool invocation context(s). + + - `:direct` + + - `:programmatic` + - `defer_loading: bool` Whether this function should be deferred and discovered via tool search. - `description: String` + - `output_schema: Hash[Symbol, untyped]` + + A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. + - `parameters: untyped` - `strict: bool` + Whether to enforce strict parameter validation. If omitted, Responses attempts to use strict validation when the schema is compatible, and falls back to non-strict validation otherwise. + - `class CustomTool` A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) @@ -75884,6 +84483,14 @@ puts(compacted_response) - `:apply_patch` + - `allowed_callers: Array[:direct | :programmatic]` + + The tool invocation context(s). + + - `:direct` + + - `:programmatic` + - `type: :tool_search_output` The type of the item. Always `tool_search_output`. @@ -75954,6 +84561,8 @@ puts(compacted_response) A tool that runs Python code to help generate a response to a prompt. + - `class ProgrammaticToolCalling` + - `class ImageGeneration` A tool that generates images using the GPT image models. @@ -76267,6 +84876,26 @@ puts(compacted_response) - `:shell_call` + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + - `:program` + - `created_by: String` The ID of the entity that created this tool call. @@ -76347,6 +84976,26 @@ puts(compacted_response) - `:shell_call_output` + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + - `:program` + - `created_by: String` The identifier of the actor that created the item. @@ -76431,6 +85080,26 @@ puts(compacted_response) - `:apply_patch_call` + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + - `:program` + - `created_by: String` The ID of the entity that created this tool call. @@ -76461,6 +85130,26 @@ puts(compacted_response) - `:apply_patch_call_output` + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + - `:program` + - `created_by: String` The ID of the entity that created this tool call output. @@ -76642,6 +85331,26 @@ puts(compacted_response) The unique ID of the custom tool call in the OpenAI platform. + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + - `:program` + - `namespace: String` The namespace of the custom tool being called. @@ -76963,6 +85672,26 @@ puts(compacted_response) The unique ID of the function tool call. + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + - `:program` + - `namespace: String` The namespace of the function to run. @@ -77015,6 +85744,16 @@ puts(compacted_response) - `:input_text` + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + + 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`. + + - `:explicit` + - `class ResponseInputImage` An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). @@ -77045,6 +85784,16 @@ puts(compacted_response) The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + + 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`. + + - `:explicit` + - `class ResponseInputFile` A file input to the model. @@ -77055,9 +85804,11 @@ puts(compacted_response) - `:input_file` - - `detail: :low | :high` + - `detail: :auto | :low | :high` - The detail level of the file to be sent to the model. Use `low` for the default rendering behavior, or `high` to render the file at higher quality. Defaults to `low`. + The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. + + - `:auto` - `:low` @@ -77079,6 +85830,16 @@ puts(compacted_response) The name of the file to be sent to the model. + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + + 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`. + + - `:explicit` + - `status: :in_progress | :completed | :incomplete` The status of the item. One of `in_progress`, `completed`, or @@ -77096,6 +85857,30 @@ puts(compacted_response) - `:function_call_output` + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + The caller type. Always `direct`. + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + The caller type. Always `program`. + + - `:program` + - `created_by: String` The identifier of the actor that created the item. @@ -77763,6 +86548,58 @@ puts(compacted_response) - `:incomplete` + - `class Program` + + - `id: String` + + The unique ID of the program item. + + - `call_id: String` + + The stable call ID of the program item. + + - `code: String` + + The JavaScript source executed by programmatic tool calling. + + - `fingerprint: String` + + Opaque program replay fingerprint that must be round-tripped. + + - `type: :program` + + The type of the item. Always `program`. + + - `:program` + + - `class ProgramOutput` + + - `id: String` + + The unique ID of the program output item. + + - `call_id: String` + + The call ID of the program item. + + - `result: String` + + The result produced by the program item. + + - `status: :completed | :incomplete` + + The terminal status of the program output item. + + - `:completed` + + - `:incomplete` + + - `type: :program_output` + + The type of the item. Always `program_output`. + + - `:program_output` + - `class ResponseToolSearchCall` - `id: String` @@ -77851,7 +86688,7 @@ puts(compacted_response) - `strict: bool` - Whether to enforce strict parameter validation. Default `true`. + Whether strict parameter validation is enforced for this function tool. - `type: :function` @@ -77859,6 +86696,14 @@ puts(compacted_response) - `:function` + - `allowed_callers: Array[:direct | :programmatic]` + + The tool invocation context(s). + + - `:direct` + + - `:programmatic` + - `defer_loading: bool` Whether this function is deferred and loaded via tool search. @@ -77867,6 +86712,10 @@ puts(compacted_response) A description of the function. Used by the model to determine whether or not to call the function. + - `output_schema: Hash[Symbol, untyped]` + + A JSON schema object describing the JSON value encoded in string outputs for this function. + - `class FileSearchTool` A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). @@ -77922,7 +86771,7 @@ puts(compacted_response) - `:nin` - - `value: String | Float | bool | Array[String | Float]` + - `value: String | Float | bool | Array[untyped]` The value to compare against the attribute key; supports string, number, or boolean types. @@ -77932,11 +86781,7 @@ puts(compacted_response) - `UnionMember2 = bool` - - `UnionMember3 = Array[String | Float]` - - - `String = String` - - - `Float = Float` + - `UnionMember3 = Array[untyped]` - `class CompoundFilter` @@ -78109,6 +86954,14 @@ puts(compacted_response) - `:mcp` + - `allowed_callers: Array[:direct | :programmatic]` + + The tool invocation context(s). + + - `:direct` + + - `:programmatic` + - `allowed_tools: Array[String] | McpToolFilter{ read_only, tool_names}` List of allowed tool names or a filter object. @@ -78327,6 +87180,22 @@ puts(compacted_response) - `:code_interpreter` + - `allowed_callers: Array[:direct | :programmatic]` + + The tool invocation context(s). + + - `:direct` + + - `:programmatic` + + - `class ProgrammaticToolCalling` + + - `type: :programmatic_tool_calling` + + The type of the tool. Always `programmatic_tool_calling`. + + - `:programmatic_tool_calling` + - `class ImageGeneration` A tool that generates images using the GPT image models. @@ -78490,6 +87359,14 @@ puts(compacted_response) - `:shell` + - `allowed_callers: Array[:direct | :programmatic]` + + The tool invocation context(s). + + - `:direct` + + - `:programmatic` + - `environment: ContainerAuto | LocalEnvironment | ContainerReference` - `class ContainerAuto` @@ -78630,6 +87507,14 @@ puts(compacted_response) - `:custom` + - `allowed_callers: Array[:direct | :programmatic]` + + The tool invocation context(s). + + - `:direct` + + - `:programmatic` + - `defer_loading: bool` Whether this tool should be deferred and discovered via tool search. @@ -78686,7 +87571,7 @@ puts(compacted_response) The namespace name used in tool calls (for example, `crm`). - - `tools: Array[Function{ name, type, defer_loading, 3 more} | CustomTool]` + - `tools: Array[Function{ name, type, allowed_callers, 5 more} | CustomTool]` The function/custom tools available inside this namespace. @@ -78698,16 +87583,30 @@ puts(compacted_response) - `:function` + - `allowed_callers: Array[:direct | :programmatic]` + + The tool invocation context(s). + + - `:direct` + + - `:programmatic` + - `defer_loading: bool` Whether this function should be deferred and discovered via tool search. - `description: String` + - `output_schema: Hash[Symbol, untyped]` + + A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. + - `parameters: untyped` - `strict: bool` + Whether to enforce strict parameter validation. If omitted, Responses attempts to use strict validation when the schema is compatible, and falls back to non-strict validation otherwise. + - `class CustomTool` A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) @@ -78808,6 +87707,14 @@ puts(compacted_response) - `:apply_patch` + - `allowed_callers: Array[:direct | :programmatic]` + + The tool invocation context(s). + + - `:direct` + + - `:programmatic` + - `type: :tool_search_output` The type of the item. Always `tool_search_output`. @@ -78878,6 +87785,8 @@ puts(compacted_response) A tool that runs Python code to help generate a response to a prompt. + - `class ProgrammaticToolCalling` + - `class ImageGeneration` A tool that generates images using the GPT image models. @@ -79191,6 +88100,26 @@ puts(compacted_response) - `:shell_call` + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + - `:program` + - `created_by: String` The ID of the entity that created this tool call. @@ -79271,6 +88200,26 @@ puts(compacted_response) - `:shell_call_output` + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + - `:program` + - `created_by: String` The identifier of the actor that created the item. @@ -79355,6 +88304,26 @@ puts(compacted_response) - `:apply_patch_call` + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + - `:program` + - `created_by: String` The ID of the entity that created this tool call. @@ -79385,6 +88354,26 @@ puts(compacted_response) - `:apply_patch_call_output` + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + - `:program` + - `created_by: String` The ID of the entity that created this tool call output. @@ -79566,6 +88555,26 @@ puts(compacted_response) The unique ID of the custom tool call in the OpenAI platform. + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + - `:program` + - `namespace: String` The namespace of the custom tool being called. @@ -79901,6 +88910,26 @@ puts(compacted_response) The unique ID of the function tool call. + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + - `:program` + - `namespace: String` The namespace of the function to run. @@ -79953,6 +88982,16 @@ puts(compacted_response) - `:input_text` + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + + 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`. + + - `:explicit` + - `class ResponseInputImage` An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). @@ -79983,6 +89022,16 @@ puts(compacted_response) The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + + 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`. + + - `:explicit` + - `class ResponseInputFile` A file input to the model. @@ -79993,9 +89042,11 @@ puts(compacted_response) - `:input_file` - - `detail: :low | :high` + - `detail: :auto | :low | :high` + + The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. - The detail level of the file to be sent to the model. Use `low` for the default rendering behavior, or `high` to render the file at higher quality. Defaults to `low`. + - `:auto` - `:low` @@ -80017,6 +89068,16 @@ puts(compacted_response) The name of the file to be sent to the model. + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + + 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`. + + - `:explicit` + - `status: :in_progress | :completed | :incomplete` The status of the item. One of `in_progress`, `completed`, or @@ -80034,6 +89095,30 @@ puts(compacted_response) - `:function_call_output` + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + The caller type. Always `direct`. + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + The caller type. Always `program`. + + - `:program` + - `created_by: String` The identifier of the actor that created the item. @@ -80701,6 +89786,58 @@ puts(compacted_response) - `:incomplete` + - `class Program` + + - `id: String` + + The unique ID of the program item. + + - `call_id: String` + + The stable call ID of the program item. + + - `code: String` + + The JavaScript source executed by programmatic tool calling. + + - `fingerprint: String` + + Opaque program replay fingerprint that must be round-tripped. + + - `type: :program` + + The type of the item. Always `program`. + + - `:program` + + - `class ProgramOutput` + + - `id: String` + + The unique ID of the program output item. + + - `call_id: String` + + The call ID of the program item. + + - `result: String` + + The result produced by the program item. + + - `status: :completed | :incomplete` + + The terminal status of the program output item. + + - `:completed` + + - `:incomplete` + + - `type: :program_output` + + The type of the item. Always `program_output`. + + - `:program_output` + - `class ResponseToolSearchCall` - `id: String` @@ -80789,7 +89926,7 @@ puts(compacted_response) - `strict: bool` - Whether to enforce strict parameter validation. Default `true`. + Whether strict parameter validation is enforced for this function tool. - `type: :function` @@ -80797,6 +89934,14 @@ puts(compacted_response) - `:function` + - `allowed_callers: Array[:direct | :programmatic]` + + The tool invocation context(s). + + - `:direct` + + - `:programmatic` + - `defer_loading: bool` Whether this function is deferred and loaded via tool search. @@ -80805,6 +89950,10 @@ puts(compacted_response) A description of the function. Used by the model to determine whether or not to call the function. + - `output_schema: Hash[Symbol, untyped]` + + A JSON schema object describing the JSON value encoded in string outputs for this function. + - `class FileSearchTool` A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). @@ -80860,7 +90009,7 @@ puts(compacted_response) - `:nin` - - `value: String | Float | bool | Array[String | Float]` + - `value: String | Float | bool | Array[untyped]` The value to compare against the attribute key; supports string, number, or boolean types. @@ -80870,11 +90019,7 @@ puts(compacted_response) - `UnionMember2 = bool` - - `UnionMember3 = Array[String | Float]` - - - `String = String` - - - `Float = Float` + - `UnionMember3 = Array[untyped]` - `class CompoundFilter` @@ -81047,6 +90192,14 @@ puts(compacted_response) - `:mcp` + - `allowed_callers: Array[:direct | :programmatic]` + + The tool invocation context(s). + + - `:direct` + + - `:programmatic` + - `allowed_tools: Array[String] | McpToolFilter{ read_only, tool_names}` List of allowed tool names or a filter object. @@ -81265,6 +90418,22 @@ puts(compacted_response) - `:code_interpreter` + - `allowed_callers: Array[:direct | :programmatic]` + + The tool invocation context(s). + + - `:direct` + + - `:programmatic` + + - `class ProgrammaticToolCalling` + + - `type: :programmatic_tool_calling` + + The type of the tool. Always `programmatic_tool_calling`. + + - `:programmatic_tool_calling` + - `class ImageGeneration` A tool that generates images using the GPT image models. @@ -81428,6 +90597,14 @@ puts(compacted_response) - `:shell` + - `allowed_callers: Array[:direct | :programmatic]` + + The tool invocation context(s). + + - `:direct` + + - `:programmatic` + - `environment: ContainerAuto | LocalEnvironment | ContainerReference` - `class ContainerAuto` @@ -81568,6 +90745,14 @@ puts(compacted_response) - `:custom` + - `allowed_callers: Array[:direct | :programmatic]` + + The tool invocation context(s). + + - `:direct` + + - `:programmatic` + - `defer_loading: bool` Whether this tool should be deferred and discovered via tool search. @@ -81624,7 +90809,7 @@ puts(compacted_response) The namespace name used in tool calls (for example, `crm`). - - `tools: Array[Function{ name, type, defer_loading, 3 more} | CustomTool]` + - `tools: Array[Function{ name, type, allowed_callers, 5 more} | CustomTool]` The function/custom tools available inside this namespace. @@ -81636,16 +90821,30 @@ puts(compacted_response) - `:function` + - `allowed_callers: Array[:direct | :programmatic]` + + The tool invocation context(s). + + - `:direct` + + - `:programmatic` + - `defer_loading: bool` Whether this function should be deferred and discovered via tool search. - `description: String` + - `output_schema: Hash[Symbol, untyped]` + + A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. + - `parameters: untyped` - `strict: bool` + Whether to enforce strict parameter validation. If omitted, Responses attempts to use strict validation when the schema is compatible, and falls back to non-strict validation otherwise. + - `class CustomTool` A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) @@ -81746,6 +90945,14 @@ puts(compacted_response) - `:apply_patch` + - `allowed_callers: Array[:direct | :programmatic]` + + The tool invocation context(s). + + - `:direct` + + - `:programmatic` + - `type: :tool_search_output` The type of the item. Always `tool_search_output`. @@ -81816,6 +91023,8 @@ puts(compacted_response) A tool that runs Python code to help generate a response to a prompt. + - `class ProgrammaticToolCalling` + - `class ImageGeneration` A tool that generates images using the GPT image models. @@ -82129,6 +91338,26 @@ puts(compacted_response) - `:shell_call` + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + - `:program` + - `created_by: String` The ID of the entity that created this tool call. @@ -82209,6 +91438,26 @@ puts(compacted_response) - `:shell_call_output` + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + - `:program` + - `created_by: String` The identifier of the actor that created the item. @@ -82293,6 +91542,26 @@ puts(compacted_response) - `:apply_patch_call` + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + - `:program` + - `created_by: String` The ID of the entity that created this tool call. @@ -82323,6 +91592,26 @@ puts(compacted_response) - `:apply_patch_call_output` + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + - `:program` + - `created_by: String` The ID of the entity that created this tool call output. @@ -82504,6 +91793,26 @@ puts(compacted_response) The unique ID of the custom tool call in the OpenAI platform. + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + - `:program` + - `namespace: String` The namespace of the custom tool being called. @@ -82953,6 +92262,16 @@ puts(compacted_response) - `:input_text` + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + + 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`. + + - `:explicit` + - `class ResponseInputImage` An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). @@ -82983,6 +92302,16 @@ puts(compacted_response) The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + + 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`. + + - `:explicit` + - `class ResponseInputFile` A file input to the model. @@ -82993,9 +92322,11 @@ puts(compacted_response) - `:input_file` - - `detail: :low | :high` + - `detail: :auto | :low | :high` + + The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. - The detail level of the file to be sent to the model. Use `low` for the default rendering behavior, or `high` to render the file at higher quality. Defaults to `low`. + - `:auto` - `:low` @@ -83017,6 +92348,16 @@ puts(compacted_response) The name of the file to be sent to the model. + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + + 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`. + + - `:explicit` + - `version: String` Optional version of the prompt template. @@ -83043,7 +92384,7 @@ puts(compacted_response) An error object returned when the model fails to generate a Response. - - `code: :server_error | :rate_limit_exceeded | :invalid_prompt | 15 more` + - `code: :server_error | :rate_limit_exceeded | :invalid_prompt | 16 more` The error code for the response. @@ -83053,6 +92394,8 @@ puts(compacted_response) - `:invalid_prompt` + - `:bio_policy` + - `:vector_store_timeout` - `:invalid_image` @@ -83153,6 +92496,16 @@ puts(compacted_response) - `:input_text` + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + + 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`. + + - `:explicit` + - `class ResponseInputImage` An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). @@ -83183,6 +92536,16 @@ puts(compacted_response) The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + + 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`. + + - `:explicit` + - `class ResponseInputFile` A file input to the model. @@ -83193,9 +92556,11 @@ puts(compacted_response) - `:input_file` - - `detail: :low | :high` + - `detail: :auto | :low | :high` - The detail level of the file to be sent to the model. Use `low` for the default rendering behavior, or `high` to render the file at higher quality. Defaults to `low`. + The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. + + - `:auto` - `:low` @@ -83217,6 +92582,16 @@ puts(compacted_response) The name of the file to be sent to the model. + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + + 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`. + + - `:explicit` + - `role: :user | :assistant | :system | :developer` The role of the message input. One of `user`, `assistant`, `system`, or @@ -84164,6 +93539,26 @@ puts(compacted_response) The unique ID of the function tool call. + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + - `:program` + - `namespace: String` The namespace of the function to run. @@ -84213,6 +93608,16 @@ puts(compacted_response) - `:input_text` + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + + 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`. + + - `:explicit` + - `class ResponseInputImageContent` An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) @@ -84243,6 +93648,16 @@ puts(compacted_response) The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + + 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`. + + - `:explicit` + - `class ResponseInputFileContent` A file input to the model. @@ -84253,9 +93668,11 @@ puts(compacted_response) - `:input_file` - - `detail: :low | :high` + - `detail: :auto | :low | :high` - The detail level of the file to be sent to the model. Use `low` for the default rendering behavior, or `high` to render the file at higher quality. Defaults to `low`. + The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. + + - `:auto` - `:low` @@ -84277,6 +93694,16 @@ puts(compacted_response) The name of the file to be sent to the model. + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + + 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`. + + - `:explicit` + - `type: :function_call_output` The type of the function tool call output. Always `function_call_output`. @@ -84287,6 +93714,30 @@ puts(compacted_response) The unique ID of the function tool call output. Populated when this item is returned via API. + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + The caller type. Always `direct`. + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + The caller type. Always `program`. + + - `:program` + - `status: :in_progress | :completed | :incomplete` The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. @@ -84355,7 +93806,7 @@ puts(compacted_response) - `strict: bool` - Whether to enforce strict parameter validation. Default `true`. + Whether strict parameter validation is enforced for this function tool. - `type: :function` @@ -84363,6 +93814,14 @@ puts(compacted_response) - `:function` + - `allowed_callers: Array[:direct | :programmatic]` + + The tool invocation context(s). + + - `:direct` + + - `:programmatic` + - `defer_loading: bool` Whether this function is deferred and loaded via tool search. @@ -84371,6 +93830,10 @@ puts(compacted_response) A description of the function. Used by the model to determine whether or not to call the function. + - `output_schema: Hash[Symbol, untyped]` + + A JSON schema object describing the JSON value encoded in string outputs for this function. + - `class FileSearchTool` A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). @@ -84426,7 +93889,7 @@ puts(compacted_response) - `:nin` - - `value: String | Float | bool | Array[String | Float]` + - `value: String | Float | bool | Array[untyped]` The value to compare against the attribute key; supports string, number, or boolean types. @@ -84436,11 +93899,7 @@ puts(compacted_response) - `UnionMember2 = bool` - - `UnionMember3 = Array[String | Float]` - - - `String = String` - - - `Float = Float` + - `UnionMember3 = Array[untyped]` - `class CompoundFilter` @@ -84613,6 +94072,14 @@ puts(compacted_response) - `:mcp` + - `allowed_callers: Array[:direct | :programmatic]` + + The tool invocation context(s). + + - `:direct` + + - `:programmatic` + - `allowed_tools: Array[String] | McpToolFilter{ read_only, tool_names}` List of allowed tool names or a filter object. @@ -84831,6 +94298,22 @@ puts(compacted_response) - `:code_interpreter` + - `allowed_callers: Array[:direct | :programmatic]` + + The tool invocation context(s). + + - `:direct` + + - `:programmatic` + + - `class ProgrammaticToolCalling` + + - `type: :programmatic_tool_calling` + + The type of the tool. Always `programmatic_tool_calling`. + + - `:programmatic_tool_calling` + - `class ImageGeneration` A tool that generates images using the GPT image models. @@ -84994,6 +94477,14 @@ puts(compacted_response) - `:shell` + - `allowed_callers: Array[:direct | :programmatic]` + + The tool invocation context(s). + + - `:direct` + + - `:programmatic` + - `environment: ContainerAuto | LocalEnvironment | ContainerReference` - `class ContainerAuto` @@ -85134,6 +94625,14 @@ puts(compacted_response) - `:custom` + - `allowed_callers: Array[:direct | :programmatic]` + + The tool invocation context(s). + + - `:direct` + + - `:programmatic` + - `defer_loading: bool` Whether this tool should be deferred and discovered via tool search. @@ -85190,7 +94689,7 @@ puts(compacted_response) The namespace name used in tool calls (for example, `crm`). - - `tools: Array[Function{ name, type, defer_loading, 3 more} | CustomTool]` + - `tools: Array[Function{ name, type, allowed_callers, 5 more} | CustomTool]` The function/custom tools available inside this namespace. @@ -85202,16 +94701,30 @@ puts(compacted_response) - `:function` + - `allowed_callers: Array[:direct | :programmatic]` + + The tool invocation context(s). + + - `:direct` + + - `:programmatic` + - `defer_loading: bool` Whether this function should be deferred and discovered via tool search. - `description: String` + - `output_schema: Hash[Symbol, untyped]` + + A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. + - `parameters: untyped` - `strict: bool` + Whether to enforce strict parameter validation. If omitted, Responses attempts to use strict validation when the schema is compatible, and falls back to non-strict validation otherwise. + - `class CustomTool` A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) @@ -85312,6 +94825,14 @@ puts(compacted_response) - `:apply_patch` + - `allowed_callers: Array[:direct | :programmatic]` + + The tool invocation context(s). + + - `:direct` + + - `:programmatic` + - `type: :tool_search_output` The item type. Always `tool_search_output`. @@ -85386,6 +94907,8 @@ puts(compacted_response) A tool that runs Python code to help generate a response to a prompt. + - `class ProgrammaticToolCalling` + - `class ImageGeneration` A tool that generates images using the GPT image models. @@ -85726,6 +95249,30 @@ puts(compacted_response) The unique ID of the shell tool call. Populated when this item is returned via API. + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + The caller type. Always `direct`. + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + The caller type. Always `program`. + + - `:program` + - `environment: LocalEnvironment | ContainerReference` The environment to execute the shell commands in. @@ -85802,6 +95349,30 @@ puts(compacted_response) The unique ID of the shell tool call output. Populated when this item is returned via API. + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + The caller type. Always `direct`. + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + The caller type. Always `program`. + + - `:program` + - `max_output_length: Integer` The maximum number of UTF-8 characters captured for this shell call's combined output. @@ -85896,6 +95467,30 @@ puts(compacted_response) The unique ID of the apply patch tool call. Populated when this item is returned via API. + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + The caller type. Always `direct`. + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + The caller type. Always `program`. + + - `:program` + - `class ApplyPatchCallOutput` The streamed output emitted by an apply patch tool call. @@ -85922,6 +95517,30 @@ puts(compacted_response) The unique ID of the apply patch tool call output. Populated when this item is returned via API. + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + The caller type. Always `direct`. + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + The caller type. Always `program`. + + - `:program` + - `output: String` Optional human-readable log text from the apply patch tool (e.g., patch results or errors). @@ -86116,6 +95735,30 @@ puts(compacted_response) The unique ID of the custom tool call output in the OpenAI platform. + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + The caller type. Always `direct`. + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + The caller type. Always `program`. + + - `:program` + - `class ResponseCustomToolCall` A call to a custom tool created by the model. @@ -86142,6 +95785,26 @@ puts(compacted_response) The unique ID of the custom tool call in the OpenAI platform. + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + - `:program` + - `namespace: String` The namespace of the custom tool being called. @@ -86170,6 +95833,58 @@ puts(compacted_response) - `:item_reference` + - `class Program` + + - `id: String` + + The unique ID of this program item. + + - `call_id: String` + + The stable call ID of the program item. + + - `code: String` + + The JavaScript source executed by programmatic tool calling. + + - `fingerprint: String` + + Opaque program replay fingerprint that must be round-tripped. + + - `type: :program` + + The item type. Always `program`. + + - `:program` + + - `class ProgramOutput` + + - `id: String` + + The unique ID of this program output item. + + - `call_id: String` + + The call ID of the program item. + + - `result: String` + + The result produced by the program item. + + - `status: :completed | :incomplete` + + The terminal status of the program output. + + - `:completed` + + - `:incomplete` + + - `type: :program_output` + + The item type. Always `program_output`. + + - `:program_output` + - `metadata: Metadata` Set of 16 key-value pairs that can be attached to an object. This can be @@ -86188,7 +95903,13 @@ puts(compacted_response) - `String = String` - - `ChatModel = :"gpt-5.4" | :"gpt-5.4-mini" | :"gpt-5.4-nano" | 75 more` + - `ChatModel = :"gpt-5.6-sol" | :"gpt-5.6-terra" | :"gpt-5.6-luna" | 78 more` + + - `:"gpt-5.6-sol"` + + - `:"gpt-5.6-terra"` + + - `:"gpt-5.6-luna"` - `:"gpt-5.4"` @@ -86459,6 +96180,30 @@ puts(compacted_response) - `:function_call_output` + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + The caller type. Always `direct`. + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + The caller type. Always `program`. + + - `:program` + - `created_by: String` The identifier of the actor that created the item. @@ -86534,6 +96279,58 @@ puts(compacted_response) for subsequent turns of a conversation if you are manually [managing context](https://platform.openai.com/docs/guides/conversation-state). + - `class Program` + + - `id: String` + + The unique ID of the program item. + + - `call_id: String` + + The stable call ID of the program item. + + - `code: String` + + The JavaScript source executed by programmatic tool calling. + + - `fingerprint: String` + + Opaque program replay fingerprint that must be round-tripped. + + - `type: :program` + + The type of the item. Always `program`. + + - `:program` + + - `class ProgramOutput` + + - `id: String` + + The unique ID of the program output item. + + - `call_id: String` + + The call ID of the program item. + + - `result: String` + + The result produced by the program item. + + - `status: :completed | :incomplete` + + The terminal status of the program output item. + + - `:completed` + + - `:incomplete` + + - `type: :program_output` + + The type of the item. Always `program_output`. + + - `:program_output` + - `class ResponseToolSearchCall` - `id: String` @@ -86638,6 +96435,8 @@ puts(compacted_response) A tool that runs Python code to help generate a response to a prompt. + - `class ProgrammaticToolCalling` + - `class ImageGeneration` A tool that generates images using the GPT image models. @@ -86740,6 +96539,8 @@ puts(compacted_response) A tool that runs Python code to help generate a response to a prompt. + - `class ProgrammaticToolCalling` + - `class ImageGeneration` A tool that generates images using the GPT image models. @@ -86988,6 +96789,26 @@ puts(compacted_response) - `:shell_call` + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + - `:program` + - `created_by: String` The ID of the entity that created this tool call. @@ -87068,6 +96889,26 @@ puts(compacted_response) - `:shell_call_output` + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + - `:program` + - `created_by: String` The identifier of the actor that created the item. @@ -87152,6 +96993,26 @@ puts(compacted_response) - `:apply_patch_call` + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + - `:program` + - `created_by: String` The ID of the entity that created this tool call. @@ -87182,6 +97043,26 @@ puts(compacted_response) - `:apply_patch_call_output` + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + - `:program` + - `created_by: String` The ID of the entity that created this tool call output. @@ -87373,7 +97254,7 @@ puts(compacted_response) What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. We generally recommend altering this or `top_p` but not both. - - `tool_choice: ToolChoiceOptions | ToolChoiceAllowed | ToolChoiceTypes | 5 more` + - `tool_choice: ToolChoiceOptions | ToolChoiceAllowed | ToolChoiceTypes | 6 more` How the model should select which tool (or tools) to use when generating a response. See the `tools` parameter to see how to specify which tools @@ -87515,6 +97396,14 @@ puts(compacted_response) - `:custom` + - `class SpecificProgrammaticToolCallingParam` + + - `type: :programmatic_tool_calling` + + The tool to call. Always `programmatic_tool_calling`. + + - `:programmatic_tool_calling` + - `class ToolChoiceApplyPatch` Forces the model to call the apply_patch tool when executing a tool call. @@ -87585,6 +97474,8 @@ puts(compacted_response) A tool that runs Python code to help generate a response to a prompt. + - `class ProgrammaticToolCalling` + - `class ImageGeneration` A tool that generates images using the GPT image models. @@ -87811,9 +97702,32 @@ puts(compacted_response) Used by OpenAI to cache responses for similar requests to optimize your cache hit rates. Replaces the `user` field. [Learn more](https://platform.openai.com/docs/guides/prompt-caching). + - `prompt_cache_options: PromptCacheOptions{ mode, ttl}` + + The prompt-caching options that were applied to the response. Supported for `gpt-5.6` and later models. + + - `mode: :implicit | :explicit` + + Whether implicit prompt-cache breakpoints were enabled. + + - `:implicit` + + - `:explicit` + + - `ttl: :"30m"` + + The minimum lifetime applied to each cache breakpoint. + + - `:"30m"` + - `prompt_cache_retention: :in_memory | :"24h"` + Deprecated. Use `prompt_cache_options.ttl` instead. + The retention policy for the prompt cache. Set to `24h` to enable extended prompt caching, which keeps cached prefixes active for longer, up to a maximum of 24 hours. [Learn more](https://platform.openai.com/docs/guides/prompt-caching#prompt-cache-retention). + This field expresses a maximum retention policy, while + `prompt_cache_options.ttl` expresses a minimum cache lifetime. The two + fields are independent and do not interact. For `gpt-5.5`, `gpt-5.5-pro`, and future models, only `24h` is supported. For older models that support both `in_memory` and `24h`, the default depends on your organization's data retention policy: @@ -87846,16 +97760,13 @@ puts(compacted_response) - `effort: ReasoningEffort` - Constrains effort on reasoning for - [reasoning models](https://platform.openai.com/docs/guides/reasoning). - Currently supported values are `none`, `minimal`, `low`, `medium`, `high`, and `xhigh`. Reducing - reasoning effort can result in faster responses and fewer tokens used - on reasoning in a response. - - - `gpt-5.1` defaults to `none`, which does not perform reasoning. The supported reasoning values for `gpt-5.1` are `none`, `low`, `medium`, and `high`. Tool calls are supported for all reasoning values in gpt-5.1. - - All models before `gpt-5.1` default to `medium` reasoning effort, and do not support `none`. - - The `gpt-5-pro` model defaults to (and only supports) `high` reasoning effort. - - `xhigh` is supported for all models after `gpt-5.1-codex-max`. + Constrains effort on reasoning for reasoning models. Currently supported + values are `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max`. + Reducing reasoning effort can result in faster responses and fewer tokens + used on reasoning in a response. Not all reasoning models support every + value. See the + [reasoning guide](https://platform.openai.com/docs/guides/reasoning) + for model-specific support. - `:none` @@ -87869,6 +97780,8 @@ puts(compacted_response) - `:xhigh` + - `:max` + - `generate_summary: :auto | :concise | :detailed` **Deprecated:** use `summary` instead. @@ -87883,6 +97796,24 @@ puts(compacted_response) - `:detailed` + - `mode: String | :standard | :pro` + + Controls the reasoning execution mode for the request. + + When returned on a response, this is the effective execution mode. + + - `String = String` + + - `Mode = :standard | :pro` + + Controls the reasoning execution mode for the request. + + When returned on a response, this is the effective execution mode. + + - `:standard` + + - `:pro` + - `summary: :auto | :concise | :detailed` A summary of the reasoning performed by the model. This can be @@ -88063,10 +97994,14 @@ puts(compacted_response) The number of input tokens. - - `input_tokens_details: InputTokensDetails{ cached_tokens}` + - `input_tokens_details: InputTokensDetails{ cache_write_tokens, cached_tokens}` A detailed breakdown of the input tokens. + - `cache_write_tokens: Integer` + + The number of input tokens that were written to the cache. + - `cached_tokens: Integer` The number of tokens that were retrieved from the cache. @@ -88251,6 +98186,13 @@ puts(compacted_response) - `:"response.reasoning_summary_part.done"` + - `status: :incomplete` + + The completion status of the summary part. Omitted when the part completed + normally and set to `incomplete` when generation was interrupted. + + - `:incomplete` + ### Response Reasoning Summary Text Delta Event - `class ResponseReasoningSummaryTextDeltaEvent` @@ -88670,7 +98612,7 @@ puts(compacted_response) An error object returned when the model fails to generate a Response. - - `code: :server_error | :rate_limit_exceeded | :invalid_prompt | 15 more` + - `code: :server_error | :rate_limit_exceeded | :invalid_prompt | 16 more` The error code for the response. @@ -88680,6 +98622,8 @@ puts(compacted_response) - `:invalid_prompt` + - `:bio_policy` + - `:vector_store_timeout` - `:invalid_image` @@ -88780,6 +98724,16 @@ puts(compacted_response) - `:input_text` + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + + 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`. + + - `:explicit` + - `class ResponseInputImage` An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). @@ -88810,6 +98764,16 @@ puts(compacted_response) The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + + 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`. + + - `:explicit` + - `class ResponseInputFile` A file input to the model. @@ -88820,9 +98784,11 @@ puts(compacted_response) - `:input_file` - - `detail: :low | :high` + - `detail: :auto | :low | :high` - The detail level of the file to be sent to the model. Use `low` for the default rendering behavior, or `high` to render the file at higher quality. Defaults to `low`. + The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. + + - `:auto` - `:low` @@ -88844,6 +98810,16 @@ puts(compacted_response) The name of the file to be sent to the model. + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + + 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`. + + - `:explicit` + - `role: :user | :assistant | :system | :developer` The role of the message input. One of `user`, `assistant`, `system`, or @@ -89791,6 +99767,26 @@ puts(compacted_response) The unique ID of the function tool call. + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + - `:program` + - `namespace: String` The namespace of the function to run. @@ -89840,6 +99836,16 @@ puts(compacted_response) - `:input_text` + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + + 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`. + + - `:explicit` + - `class ResponseInputImageContent` An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) @@ -89870,6 +99876,16 @@ puts(compacted_response) The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + + 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`. + + - `:explicit` + - `class ResponseInputFileContent` A file input to the model. @@ -89880,9 +99896,11 @@ puts(compacted_response) - `:input_file` - - `detail: :low | :high` + - `detail: :auto | :low | :high` + + The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. - The detail level of the file to be sent to the model. Use `low` for the default rendering behavior, or `high` to render the file at higher quality. Defaults to `low`. + - `:auto` - `:low` @@ -89904,6 +99922,16 @@ puts(compacted_response) The name of the file to be sent to the model. + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + + 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`. + + - `:explicit` + - `type: :function_call_output` The type of the function tool call output. Always `function_call_output`. @@ -89914,6 +99942,30 @@ puts(compacted_response) The unique ID of the function tool call output. Populated when this item is returned via API. + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + The caller type. Always `direct`. + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + The caller type. Always `program`. + + - `:program` + - `status: :in_progress | :completed | :incomplete` The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. @@ -89982,7 +100034,7 @@ puts(compacted_response) - `strict: bool` - Whether to enforce strict parameter validation. Default `true`. + Whether strict parameter validation is enforced for this function tool. - `type: :function` @@ -89990,6 +100042,14 @@ puts(compacted_response) - `:function` + - `allowed_callers: Array[:direct | :programmatic]` + + The tool invocation context(s). + + - `:direct` + + - `:programmatic` + - `defer_loading: bool` Whether this function is deferred and loaded via tool search. @@ -89998,6 +100058,10 @@ puts(compacted_response) A description of the function. Used by the model to determine whether or not to call the function. + - `output_schema: Hash[Symbol, untyped]` + + A JSON schema object describing the JSON value encoded in string outputs for this function. + - `class FileSearchTool` A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). @@ -90053,7 +100117,7 @@ puts(compacted_response) - `:nin` - - `value: String | Float | bool | Array[String | Float]` + - `value: String | Float | bool | Array[untyped]` The value to compare against the attribute key; supports string, number, or boolean types. @@ -90063,11 +100127,7 @@ puts(compacted_response) - `UnionMember2 = bool` - - `UnionMember3 = Array[String | Float]` - - - `String = String` - - - `Float = Float` + - `UnionMember3 = Array[untyped]` - `class CompoundFilter` @@ -90240,6 +100300,14 @@ puts(compacted_response) - `:mcp` + - `allowed_callers: Array[:direct | :programmatic]` + + The tool invocation context(s). + + - `:direct` + + - `:programmatic` + - `allowed_tools: Array[String] | McpToolFilter{ read_only, tool_names}` List of allowed tool names or a filter object. @@ -90458,6 +100526,22 @@ puts(compacted_response) - `:code_interpreter` + - `allowed_callers: Array[:direct | :programmatic]` + + The tool invocation context(s). + + - `:direct` + + - `:programmatic` + + - `class ProgrammaticToolCalling` + + - `type: :programmatic_tool_calling` + + The type of the tool. Always `programmatic_tool_calling`. + + - `:programmatic_tool_calling` + - `class ImageGeneration` A tool that generates images using the GPT image models. @@ -90621,6 +100705,14 @@ puts(compacted_response) - `:shell` + - `allowed_callers: Array[:direct | :programmatic]` + + The tool invocation context(s). + + - `:direct` + + - `:programmatic` + - `environment: ContainerAuto | LocalEnvironment | ContainerReference` - `class ContainerAuto` @@ -90761,6 +100853,14 @@ puts(compacted_response) - `:custom` + - `allowed_callers: Array[:direct | :programmatic]` + + The tool invocation context(s). + + - `:direct` + + - `:programmatic` + - `defer_loading: bool` Whether this tool should be deferred and discovered via tool search. @@ -90817,7 +100917,7 @@ puts(compacted_response) The namespace name used in tool calls (for example, `crm`). - - `tools: Array[Function{ name, type, defer_loading, 3 more} | CustomTool]` + - `tools: Array[Function{ name, type, allowed_callers, 5 more} | CustomTool]` The function/custom tools available inside this namespace. @@ -90829,16 +100929,30 @@ puts(compacted_response) - `:function` + - `allowed_callers: Array[:direct | :programmatic]` + + The tool invocation context(s). + + - `:direct` + + - `:programmatic` + - `defer_loading: bool` Whether this function should be deferred and discovered via tool search. - `description: String` + - `output_schema: Hash[Symbol, untyped]` + + A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. + - `parameters: untyped` - `strict: bool` + Whether to enforce strict parameter validation. If omitted, Responses attempts to use strict validation when the schema is compatible, and falls back to non-strict validation otherwise. + - `class CustomTool` A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) @@ -90939,6 +101053,14 @@ puts(compacted_response) - `:apply_patch` + - `allowed_callers: Array[:direct | :programmatic]` + + The tool invocation context(s). + + - `:direct` + + - `:programmatic` + - `type: :tool_search_output` The item type. Always `tool_search_output`. @@ -91013,6 +101135,8 @@ puts(compacted_response) A tool that runs Python code to help generate a response to a prompt. + - `class ProgrammaticToolCalling` + - `class ImageGeneration` A tool that generates images using the GPT image models. @@ -91353,6 +101477,30 @@ puts(compacted_response) The unique ID of the shell tool call. Populated when this item is returned via API. + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + The caller type. Always `direct`. + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + The caller type. Always `program`. + + - `:program` + - `environment: LocalEnvironment | ContainerReference` The environment to execute the shell commands in. @@ -91429,6 +101577,30 @@ puts(compacted_response) The unique ID of the shell tool call output. Populated when this item is returned via API. + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + The caller type. Always `direct`. + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + The caller type. Always `program`. + + - `:program` + - `max_output_length: Integer` The maximum number of UTF-8 characters captured for this shell call's combined output. @@ -91523,6 +101695,30 @@ puts(compacted_response) The unique ID of the apply patch tool call. Populated when this item is returned via API. + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + The caller type. Always `direct`. + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + The caller type. Always `program`. + + - `:program` + - `class ApplyPatchCallOutput` The streamed output emitted by an apply patch tool call. @@ -91549,6 +101745,30 @@ puts(compacted_response) The unique ID of the apply patch tool call output. Populated when this item is returned via API. + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + The caller type. Always `direct`. + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + The caller type. Always `program`. + + - `:program` + - `output: String` Optional human-readable log text from the apply patch tool (e.g., patch results or errors). @@ -91743,6 +101963,30 @@ puts(compacted_response) The unique ID of the custom tool call output in the OpenAI platform. + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + The caller type. Always `direct`. + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + The caller type. Always `program`. + + - `:program` + - `class ResponseCustomToolCall` A call to a custom tool created by the model. @@ -91769,6 +102013,26 @@ puts(compacted_response) The unique ID of the custom tool call in the OpenAI platform. + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + - `:program` + - `namespace: String` The namespace of the custom tool being called. @@ -91797,6 +102061,58 @@ puts(compacted_response) - `:item_reference` + - `class Program` + + - `id: String` + + The unique ID of this program item. + + - `call_id: String` + + The stable call ID of the program item. + + - `code: String` + + The JavaScript source executed by programmatic tool calling. + + - `fingerprint: String` + + Opaque program replay fingerprint that must be round-tripped. + + - `type: :program` + + The item type. Always `program`. + + - `:program` + + - `class ProgramOutput` + + - `id: String` + + The unique ID of this program output item. + + - `call_id: String` + + The call ID of the program item. + + - `result: String` + + The result produced by the program item. + + - `status: :completed | :incomplete` + + The terminal status of the program output. + + - `:completed` + + - `:incomplete` + + - `type: :program_output` + + The item type. Always `program_output`. + + - `:program_output` + - `metadata: Metadata` Set of 16 key-value pairs that can be attached to an object. This can be @@ -91815,7 +102131,13 @@ puts(compacted_response) - `String = String` - - `ChatModel = :"gpt-5.4" | :"gpt-5.4-mini" | :"gpt-5.4-nano" | 75 more` + - `ChatModel = :"gpt-5.6-sol" | :"gpt-5.6-terra" | :"gpt-5.6-luna" | 78 more` + + - `:"gpt-5.6-sol"` + + - `:"gpt-5.6-terra"` + + - `:"gpt-5.6-luna"` - `:"gpt-5.4"` @@ -92086,6 +102408,30 @@ puts(compacted_response) - `:function_call_output` + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + The caller type. Always `direct`. + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + The caller type. Always `program`. + + - `:program` + - `created_by: String` The identifier of the actor that created the item. @@ -92161,6 +102507,58 @@ puts(compacted_response) for subsequent turns of a conversation if you are manually [managing context](https://platform.openai.com/docs/guides/conversation-state). + - `class Program` + + - `id: String` + + The unique ID of the program item. + + - `call_id: String` + + The stable call ID of the program item. + + - `code: String` + + The JavaScript source executed by programmatic tool calling. + + - `fingerprint: String` + + Opaque program replay fingerprint that must be round-tripped. + + - `type: :program` + + The type of the item. Always `program`. + + - `:program` + + - `class ProgramOutput` + + - `id: String` + + The unique ID of the program output item. + + - `call_id: String` + + The call ID of the program item. + + - `result: String` + + The result produced by the program item. + + - `status: :completed | :incomplete` + + The terminal status of the program output item. + + - `:completed` + + - `:incomplete` + + - `type: :program_output` + + The type of the item. Always `program_output`. + + - `:program_output` + - `class ResponseToolSearchCall` - `id: String` @@ -92265,6 +102663,8 @@ puts(compacted_response) A tool that runs Python code to help generate a response to a prompt. + - `class ProgrammaticToolCalling` + - `class ImageGeneration` A tool that generates images using the GPT image models. @@ -92367,6 +102767,8 @@ puts(compacted_response) A tool that runs Python code to help generate a response to a prompt. + - `class ProgrammaticToolCalling` + - `class ImageGeneration` A tool that generates images using the GPT image models. @@ -92615,6 +103017,26 @@ puts(compacted_response) - `:shell_call` + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + - `:program` + - `created_by: String` The ID of the entity that created this tool call. @@ -92695,6 +103117,26 @@ puts(compacted_response) - `:shell_call_output` + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + - `:program` + - `created_by: String` The identifier of the actor that created the item. @@ -92779,6 +103221,26 @@ puts(compacted_response) - `:apply_patch_call` + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + - `:program` + - `created_by: String` The ID of the entity that created this tool call. @@ -92809,6 +103271,26 @@ puts(compacted_response) - `:apply_patch_call_output` + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + - `:program` + - `created_by: String` The ID of the entity that created this tool call output. @@ -93000,7 +103482,7 @@ puts(compacted_response) What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. We generally recommend altering this or `top_p` but not both. - - `tool_choice: ToolChoiceOptions | ToolChoiceAllowed | ToolChoiceTypes | 5 more` + - `tool_choice: ToolChoiceOptions | ToolChoiceAllowed | ToolChoiceTypes | 6 more` How the model should select which tool (or tools) to use when generating a response. See the `tools` parameter to see how to specify which tools @@ -93142,6 +103624,14 @@ puts(compacted_response) - `:custom` + - `class SpecificProgrammaticToolCallingParam` + + - `type: :programmatic_tool_calling` + + The tool to call. Always `programmatic_tool_calling`. + + - `:programmatic_tool_calling` + - `class ToolChoiceApplyPatch` Forces the model to call the apply_patch tool when executing a tool call. @@ -93212,6 +103702,8 @@ puts(compacted_response) A tool that runs Python code to help generate a response to a prompt. + - `class ProgrammaticToolCalling` + - `class ImageGeneration` A tool that generates images using the GPT image models. @@ -93438,9 +103930,32 @@ puts(compacted_response) Used by OpenAI to cache responses for similar requests to optimize your cache hit rates. Replaces the `user` field. [Learn more](https://platform.openai.com/docs/guides/prompt-caching). + - `prompt_cache_options: PromptCacheOptions{ mode, ttl}` + + The prompt-caching options that were applied to the response. Supported for `gpt-5.6` and later models. + + - `mode: :implicit | :explicit` + + Whether implicit prompt-cache breakpoints were enabled. + + - `:implicit` + + - `:explicit` + + - `ttl: :"30m"` + + The minimum lifetime applied to each cache breakpoint. + + - `:"30m"` + - `prompt_cache_retention: :in_memory | :"24h"` + Deprecated. Use `prompt_cache_options.ttl` instead. + The retention policy for the prompt cache. Set to `24h` to enable extended prompt caching, which keeps cached prefixes active for longer, up to a maximum of 24 hours. [Learn more](https://platform.openai.com/docs/guides/prompt-caching#prompt-cache-retention). + This field expresses a maximum retention policy, while + `prompt_cache_options.ttl` expresses a minimum cache lifetime. The two + fields are independent and do not interact. For `gpt-5.5`, `gpt-5.5-pro`, and future models, only `24h` is supported. For older models that support both `in_memory` and `24h`, the default depends on your organization's data retention policy: @@ -93473,16 +103988,13 @@ puts(compacted_response) - `effort: ReasoningEffort` - Constrains effort on reasoning for - [reasoning models](https://platform.openai.com/docs/guides/reasoning). - Currently supported values are `none`, `minimal`, `low`, `medium`, `high`, and `xhigh`. Reducing - reasoning effort can result in faster responses and fewer tokens used - on reasoning in a response. - - - `gpt-5.1` defaults to `none`, which does not perform reasoning. The supported reasoning values for `gpt-5.1` are `none`, `low`, `medium`, and `high`. Tool calls are supported for all reasoning values in gpt-5.1. - - All models before `gpt-5.1` default to `medium` reasoning effort, and do not support `none`. - - The `gpt-5-pro` model defaults to (and only supports) `high` reasoning effort. - - `xhigh` is supported for all models after `gpt-5.1-codex-max`. + Constrains effort on reasoning for reasoning models. Currently supported + values are `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max`. + Reducing reasoning effort can result in faster responses and fewer tokens + used on reasoning in a response. Not all reasoning models support every + value. See the + [reasoning guide](https://platform.openai.com/docs/guides/reasoning) + for model-specific support. - `:none` @@ -93496,6 +104008,8 @@ puts(compacted_response) - `:xhigh` + - `:max` + - `generate_summary: :auto | :concise | :detailed` **Deprecated:** use `summary` instead. @@ -93510,6 +104024,24 @@ puts(compacted_response) - `:detailed` + - `mode: String | :standard | :pro` + + Controls the reasoning execution mode for the request. + + When returned on a response, this is the effective execution mode. + + - `String = String` + + - `Mode = :standard | :pro` + + Controls the reasoning execution mode for the request. + + When returned on a response, this is the effective execution mode. + + - `:standard` + + - `:pro` + - `summary: :auto | :concise | :detailed` A summary of the reasoning performed by the model. This can be @@ -93690,10 +104222,14 @@ puts(compacted_response) The number of input tokens. - - `input_tokens_details: InputTokensDetails{ cached_tokens}` + - `input_tokens_details: InputTokensDetails{ cache_write_tokens, cached_tokens}` A detailed breakdown of the input tokens. + - `cache_write_tokens: Integer` + + The number of input tokens that were written to the cache. + - `cached_tokens: Integer` The number of tokens that were retrieved from the cache. @@ -94096,6 +104632,10 @@ puts(compacted_response) for subsequent turns of a conversation if you are manually [managing context](https://platform.openai.com/docs/guides/conversation-state). + - `class Program` + + - `class ProgramOutput` + - `class ResponseToolSearchCall` - `class ResponseToolSearchOutputItem` @@ -94278,6 +104818,13 @@ puts(compacted_response) - `:"response.reasoning_summary_part.done"` + - `status: :incomplete` + + The completion status of the summary part. Omitted when the part completed + normally and set to `incomplete` when generation was interrupted. + + - `:incomplete` + - `class ResponseReasoningSummaryTextDeltaEvent` Emitted when a delta is added to a reasoning summary text. @@ -95315,7 +105862,7 @@ puts(compacted_response) - `strict: bool` - Whether to enforce strict parameter validation. Default `true`. + Whether strict parameter validation is enforced for this function tool. - `type: :function` @@ -95323,6 +105870,14 @@ puts(compacted_response) - `:function` + - `allowed_callers: Array[:direct | :programmatic]` + + The tool invocation context(s). + + - `:direct` + + - `:programmatic` + - `defer_loading: bool` Whether this function is deferred and loaded via tool search. @@ -95331,6 +105886,10 @@ puts(compacted_response) A description of the function. Used by the model to determine whether or not to call the function. + - `output_schema: Hash[Symbol, untyped]` + + A JSON schema object describing the JSON value encoded in string outputs for this function. + - `class FileSearchTool` A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). @@ -95386,7 +105945,7 @@ puts(compacted_response) - `:nin` - - `value: String | Float | bool | Array[String | Float]` + - `value: String | Float | bool | Array[untyped]` The value to compare against the attribute key; supports string, number, or boolean types. @@ -95396,11 +105955,7 @@ puts(compacted_response) - `UnionMember2 = bool` - - `UnionMember3 = Array[String | Float]` - - - `String = String` - - - `Float = Float` + - `UnionMember3 = Array[untyped]` - `class CompoundFilter` @@ -95573,6 +106128,14 @@ puts(compacted_response) - `:mcp` + - `allowed_callers: Array[:direct | :programmatic]` + + The tool invocation context(s). + + - `:direct` + + - `:programmatic` + - `allowed_tools: Array[String] | McpToolFilter{ read_only, tool_names}` List of allowed tool names or a filter object. @@ -95791,6 +106354,22 @@ puts(compacted_response) - `:code_interpreter` + - `allowed_callers: Array[:direct | :programmatic]` + + The tool invocation context(s). + + - `:direct` + + - `:programmatic` + + - `class ProgrammaticToolCalling` + + - `type: :programmatic_tool_calling` + + The type of the tool. Always `programmatic_tool_calling`. + + - `:programmatic_tool_calling` + - `class ImageGeneration` A tool that generates images using the GPT image models. @@ -95954,6 +106533,14 @@ puts(compacted_response) - `:shell` + - `allowed_callers: Array[:direct | :programmatic]` + + The tool invocation context(s). + + - `:direct` + + - `:programmatic` + - `environment: ContainerAuto | LocalEnvironment | ContainerReference` - `class ContainerAuto` @@ -96094,6 +106681,14 @@ puts(compacted_response) - `:custom` + - `allowed_callers: Array[:direct | :programmatic]` + + The tool invocation context(s). + + - `:direct` + + - `:programmatic` + - `defer_loading: bool` Whether this tool should be deferred and discovered via tool search. @@ -96150,7 +106745,7 @@ puts(compacted_response) The namespace name used in tool calls (for example, `crm`). - - `tools: Array[Function{ name, type, defer_loading, 3 more} | CustomTool]` + - `tools: Array[Function{ name, type, allowed_callers, 5 more} | CustomTool]` The function/custom tools available inside this namespace. @@ -96162,16 +106757,30 @@ puts(compacted_response) - `:function` + - `allowed_callers: Array[:direct | :programmatic]` + + The tool invocation context(s). + + - `:direct` + + - `:programmatic` + - `defer_loading: bool` Whether this function should be deferred and discovered via tool search. - `description: String` + - `output_schema: Hash[Symbol, untyped]` + + A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. + - `parameters: untyped` - `strict: bool` + Whether to enforce strict parameter validation. If omitted, Responses attempts to use strict validation when the schema is compatible, and falls back to non-strict validation otherwise. + - `class CustomTool` A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) @@ -96272,6 +106881,14 @@ puts(compacted_response) - `:apply_patch` + - `allowed_callers: Array[:direct | :programmatic]` + + The tool invocation context(s). + + - `:direct` + + - `:programmatic` + - `type: :tool_search_output` The type of the item. Always `tool_search_output`. @@ -96304,7 +106921,7 @@ puts(compacted_response) - `strict: bool` - Whether to enforce strict parameter validation. Default `true`. + Whether strict parameter validation is enforced for this function tool. - `type: :function` @@ -96312,6 +106929,14 @@ puts(compacted_response) - `:function` + - `allowed_callers: Array[:direct | :programmatic]` + + The tool invocation context(s). + + - `:direct` + + - `:programmatic` + - `defer_loading: bool` Whether this function is deferred and loaded via tool search. @@ -96320,6 +106945,10 @@ puts(compacted_response) A description of the function. Used by the model to determine whether or not to call the function. + - `output_schema: Hash[Symbol, untyped]` + + A JSON schema object describing the JSON value encoded in string outputs for this function. + - `class FileSearchTool` A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). @@ -96375,7 +107004,7 @@ puts(compacted_response) - `:nin` - - `value: String | Float | bool | Array[String | Float]` + - `value: String | Float | bool | Array[untyped]` The value to compare against the attribute key; supports string, number, or boolean types. @@ -96385,11 +107014,7 @@ puts(compacted_response) - `UnionMember2 = bool` - - `UnionMember3 = Array[String | Float]` - - - `String = String` - - - `Float = Float` + - `UnionMember3 = Array[untyped]` - `class CompoundFilter` @@ -96562,6 +107187,14 @@ puts(compacted_response) - `:mcp` + - `allowed_callers: Array[:direct | :programmatic]` + + The tool invocation context(s). + + - `:direct` + + - `:programmatic` + - `allowed_tools: Array[String] | McpToolFilter{ read_only, tool_names}` List of allowed tool names or a filter object. @@ -96780,6 +107413,22 @@ puts(compacted_response) - `:code_interpreter` + - `allowed_callers: Array[:direct | :programmatic]` + + The tool invocation context(s). + + - `:direct` + + - `:programmatic` + + - `class ProgrammaticToolCalling` + + - `type: :programmatic_tool_calling` + + The type of the tool. Always `programmatic_tool_calling`. + + - `:programmatic_tool_calling` + - `class ImageGeneration` A tool that generates images using the GPT image models. @@ -96943,6 +107592,14 @@ puts(compacted_response) - `:shell` + - `allowed_callers: Array[:direct | :programmatic]` + + The tool invocation context(s). + + - `:direct` + + - `:programmatic` + - `environment: ContainerAuto | LocalEnvironment | ContainerReference` - `class ContainerAuto` @@ -97083,6 +107740,14 @@ puts(compacted_response) - `:custom` + - `allowed_callers: Array[:direct | :programmatic]` + + The tool invocation context(s). + + - `:direct` + + - `:programmatic` + - `defer_loading: bool` Whether this tool should be deferred and discovered via tool search. @@ -97139,7 +107804,7 @@ puts(compacted_response) The namespace name used in tool calls (for example, `crm`). - - `tools: Array[Function{ name, type, defer_loading, 3 more} | CustomTool]` + - `tools: Array[Function{ name, type, allowed_callers, 5 more} | CustomTool]` The function/custom tools available inside this namespace. @@ -97151,16 +107816,30 @@ puts(compacted_response) - `:function` + - `allowed_callers: Array[:direct | :programmatic]` + + The tool invocation context(s). + + - `:direct` + + - `:programmatic` + - `defer_loading: bool` Whether this function should be deferred and discovered via tool search. - `description: String` + - `output_schema: Hash[Symbol, untyped]` + + A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. + - `parameters: untyped` - `strict: bool` + Whether to enforce strict parameter validation. If omitted, Responses attempts to use strict validation when the schema is compatible, and falls back to non-strict validation otherwise. + - `class CustomTool` A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) @@ -97261,6 +107940,14 @@ puts(compacted_response) - `:apply_patch` + - `allowed_callers: Array[:direct | :programmatic]` + + The tool invocation context(s). + + - `:direct` + + - `:programmatic` + - `type: :tool_search_output` The item type. Always `tool_search_output`. @@ -97304,10 +107991,14 @@ puts(compacted_response) The number of input tokens. - - `input_tokens_details: InputTokensDetails{ cached_tokens}` + - `input_tokens_details: InputTokensDetails{ cache_write_tokens, cached_tokens}` A detailed breakdown of the input tokens. + - `cache_write_tokens: Integer` + + The number of input tokens that were written to the cache. + - `cached_tokens: Integer` The number of tokens that were retrieved from the cache. @@ -97531,6 +108222,16 @@ puts(compacted_response) - `:input_text` + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + + 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`. + + - `:explicit` + - `class ResponseInputImage` An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). @@ -97561,6 +108262,16 @@ puts(compacted_response) The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + + 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`. + + - `:explicit` + - `class ResponseInputFile` A file input to the model. @@ -97571,9 +108282,11 @@ puts(compacted_response) - `:input_file` - - `detail: :low | :high` + - `detail: :auto | :low | :high` + + The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. - The detail level of the file to be sent to the model. Use `low` for the default rendering behavior, or `high` to render the file at higher quality. Defaults to `low`. + - `:auto` - `:low` @@ -97595,6 +108308,16 @@ puts(compacted_response) The name of the file to be sent to the model. + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + + 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`. + + - `:explicit` + - `role: :user | :assistant | :system | :developer` The role of the message input. One of `user`, `assistant`, `system`, or @@ -98542,6 +109265,26 @@ puts(compacted_response) The unique ID of the function tool call. + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + - `:program` + - `namespace: String` The namespace of the function to run. @@ -98591,6 +109334,16 @@ puts(compacted_response) - `:input_text` + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + + 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`. + + - `:explicit` + - `class ResponseInputImageContent` An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) @@ -98621,6 +109374,16 @@ puts(compacted_response) The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + + 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`. + + - `:explicit` + - `class ResponseInputFileContent` A file input to the model. @@ -98631,9 +109394,11 @@ puts(compacted_response) - `:input_file` - - `detail: :low | :high` + - `detail: :auto | :low | :high` - The detail level of the file to be sent to the model. Use `low` for the default rendering behavior, or `high` to render the file at higher quality. Defaults to `low`. + The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. + + - `:auto` - `:low` @@ -98655,6 +109420,16 @@ puts(compacted_response) The name of the file to be sent to the model. + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + + 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`. + + - `:explicit` + - `type: :function_call_output` The type of the function tool call output. Always `function_call_output`. @@ -98665,6 +109440,30 @@ puts(compacted_response) The unique ID of the function tool call output. Populated when this item is returned via API. + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + The caller type. Always `direct`. + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + The caller type. Always `program`. + + - `:program` + - `status: :in_progress | :completed | :incomplete` The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. @@ -98733,7 +109532,7 @@ puts(compacted_response) - `strict: bool` - Whether to enforce strict parameter validation. Default `true`. + Whether strict parameter validation is enforced for this function tool. - `type: :function` @@ -98741,6 +109540,14 @@ puts(compacted_response) - `:function` + - `allowed_callers: Array[:direct | :programmatic]` + + The tool invocation context(s). + + - `:direct` + + - `:programmatic` + - `defer_loading: bool` Whether this function is deferred and loaded via tool search. @@ -98749,6 +109556,10 @@ puts(compacted_response) A description of the function. Used by the model to determine whether or not to call the function. + - `output_schema: Hash[Symbol, untyped]` + + A JSON schema object describing the JSON value encoded in string outputs for this function. + - `class FileSearchTool` A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). @@ -98804,7 +109615,7 @@ puts(compacted_response) - `:nin` - - `value: String | Float | bool | Array[String | Float]` + - `value: String | Float | bool | Array[untyped]` The value to compare against the attribute key; supports string, number, or boolean types. @@ -98814,11 +109625,7 @@ puts(compacted_response) - `UnionMember2 = bool` - - `UnionMember3 = Array[String | Float]` - - - `String = String` - - - `Float = Float` + - `UnionMember3 = Array[untyped]` - `class CompoundFilter` @@ -98991,6 +109798,14 @@ puts(compacted_response) - `:mcp` + - `allowed_callers: Array[:direct | :programmatic]` + + The tool invocation context(s). + + - `:direct` + + - `:programmatic` + - `allowed_tools: Array[String] | McpToolFilter{ read_only, tool_names}` List of allowed tool names or a filter object. @@ -99209,6 +110024,22 @@ puts(compacted_response) - `:code_interpreter` + - `allowed_callers: Array[:direct | :programmatic]` + + The tool invocation context(s). + + - `:direct` + + - `:programmatic` + + - `class ProgrammaticToolCalling` + + - `type: :programmatic_tool_calling` + + The type of the tool. Always `programmatic_tool_calling`. + + - `:programmatic_tool_calling` + - `class ImageGeneration` A tool that generates images using the GPT image models. @@ -99372,6 +110203,14 @@ puts(compacted_response) - `:shell` + - `allowed_callers: Array[:direct | :programmatic]` + + The tool invocation context(s). + + - `:direct` + + - `:programmatic` + - `environment: ContainerAuto | LocalEnvironment | ContainerReference` - `class ContainerAuto` @@ -99512,6 +110351,14 @@ puts(compacted_response) - `:custom` + - `allowed_callers: Array[:direct | :programmatic]` + + The tool invocation context(s). + + - `:direct` + + - `:programmatic` + - `defer_loading: bool` Whether this tool should be deferred and discovered via tool search. @@ -99568,7 +110415,7 @@ puts(compacted_response) The namespace name used in tool calls (for example, `crm`). - - `tools: Array[Function{ name, type, defer_loading, 3 more} | CustomTool]` + - `tools: Array[Function{ name, type, allowed_callers, 5 more} | CustomTool]` The function/custom tools available inside this namespace. @@ -99580,16 +110427,30 @@ puts(compacted_response) - `:function` + - `allowed_callers: Array[:direct | :programmatic]` + + The tool invocation context(s). + + - `:direct` + + - `:programmatic` + - `defer_loading: bool` Whether this function should be deferred and discovered via tool search. - `description: String` + - `output_schema: Hash[Symbol, untyped]` + + A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. + - `parameters: untyped` - `strict: bool` + Whether to enforce strict parameter validation. If omitted, Responses attempts to use strict validation when the schema is compatible, and falls back to non-strict validation otherwise. + - `class CustomTool` A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) @@ -99690,6 +110551,14 @@ puts(compacted_response) - `:apply_patch` + - `allowed_callers: Array[:direct | :programmatic]` + + The tool invocation context(s). + + - `:direct` + + - `:programmatic` + - `type: :tool_search_output` The item type. Always `tool_search_output`. @@ -99764,6 +110633,8 @@ puts(compacted_response) A tool that runs Python code to help generate a response to a prompt. + - `class ProgrammaticToolCalling` + - `class ImageGeneration` A tool that generates images using the GPT image models. @@ -100104,6 +110975,30 @@ puts(compacted_response) The unique ID of the shell tool call. Populated when this item is returned via API. + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + The caller type. Always `direct`. + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + The caller type. Always `program`. + + - `:program` + - `environment: LocalEnvironment | ContainerReference` The environment to execute the shell commands in. @@ -100180,6 +111075,30 @@ puts(compacted_response) The unique ID of the shell tool call output. Populated when this item is returned via API. + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + The caller type. Always `direct`. + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + The caller type. Always `program`. + + - `:program` + - `max_output_length: Integer` The maximum number of UTF-8 characters captured for this shell call's combined output. @@ -100274,6 +111193,30 @@ puts(compacted_response) The unique ID of the apply patch tool call. Populated when this item is returned via API. + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + The caller type. Always `direct`. + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + The caller type. Always `program`. + + - `:program` + - `class ApplyPatchCallOutput` The streamed output emitted by an apply patch tool call. @@ -100300,6 +111243,30 @@ puts(compacted_response) The unique ID of the apply patch tool call output. Populated when this item is returned via API. + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + The caller type. Always `direct`. + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + The caller type. Always `program`. + + - `:program` + - `output: String` Optional human-readable log text from the apply patch tool (e.g., patch results or errors). @@ -100494,6 +111461,30 @@ puts(compacted_response) The unique ID of the custom tool call output in the OpenAI platform. + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + The caller type. Always `direct`. + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + The caller type. Always `program`. + + - `:program` + - `class ResponseCustomToolCall` A call to a custom tool created by the model. @@ -100520,6 +111511,26 @@ puts(compacted_response) The unique ID of the custom tool call in the OpenAI platform. + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + - `:program` + - `namespace: String` The namespace of the custom tool being called. @@ -100548,6 +111559,58 @@ puts(compacted_response) - `:item_reference` + - `class Program` + + - `id: String` + + The unique ID of this program item. + + - `call_id: String` + + The stable call ID of the program item. + + - `code: String` + + The JavaScript source executed by programmatic tool calling. + + - `fingerprint: String` + + Opaque program replay fingerprint that must be round-tripped. + + - `type: :program` + + The item type. Always `program`. + + - `:program` + + - `class ProgramOutput` + + - `id: String` + + The unique ID of this program output item. + + - `call_id: String` + + The call ID of the program item. + + - `result: String` + + The result produced by the program item. + + - `status: :completed | :incomplete` + + The terminal status of the program output. + + - `:completed` + + - `:incomplete` + + - `type: :program_output` + + The item type. Always `program_output`. + + - `:program_output` + - `instructions: String` A system (or developer) message inserted into the model's context. @@ -100582,7 +111645,13 @@ puts(compacted_response) - `String = String` - - `ChatModel = :"gpt-5.4" | :"gpt-5.4-mini" | :"gpt-5.4-nano" | 75 more` + - `ChatModel = :"gpt-5.6-sol" | :"gpt-5.6-terra" | :"gpt-5.6-luna" | 78 more` + + - `:"gpt-5.6-sol"` + + - `:"gpt-5.6-terra"` + + - `:"gpt-5.6-luna"` - `:"gpt-5.4"` @@ -100770,7 +111839,7 @@ puts(compacted_response) - `:"gpt-5.1-codex-max"` - - `moderation: Moderation{ model}` + - `moderation: Moderation{ model, policy}` Configuration for running moderation on the input and output of this response. @@ -100778,6 +111847,30 @@ puts(compacted_response) The moderation model to use for moderated completions, e.g. 'omni-moderation-latest'. + - `policy: Policy{ input, output}` + + The policy to apply to moderated response input and output. + + - `input: Input{ mode}` + + The moderation policy for the response input. + + - `mode: :score | :block` + + - `:score` + + - `:block` + + - `output: Output{ mode}` + + The moderation policy for the response output. + + - `mode: :score | :block` + + - `:score` + + - `:block` + - `parallel_tool_calls: bool` Whether to allow the model to run tool calls in parallel. @@ -100825,9 +111918,32 @@ puts(compacted_response) Used by OpenAI to cache responses for similar requests to optimize your cache hit rates. Replaces the `user` field. [Learn more](https://platform.openai.com/docs/guides/prompt-caching). + - `prompt_cache_options: PromptCacheOptions{ mode, ttl}` + + 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](https://platform.openai.com/docs/guides/prompt-caching) for current details. + + - `mode: :implicit | :explicit` + + 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. + + - `:implicit` + + - `:explicit` + + - `ttl: :"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. + + - `:"30m"` + - `prompt_cache_retention: :in_memory | :"24h"` + Deprecated. Use `prompt_cache_options.ttl` instead. + The retention policy for the prompt cache. Set to `24h` to enable extended prompt caching, which keeps cached prefixes active for longer, up to a maximum of 24 hours. [Learn more](https://platform.openai.com/docs/guides/prompt-caching#prompt-cache-retention). + This field expresses a maximum retention policy, while + `prompt_cache_options.ttl` expresses a minimum cache lifetime. The two + fields are independent and do not interact. For `gpt-5.5`, `gpt-5.5-pro`, and future models, only `24h` is supported. For older models that support both `in_memory` and `24h`, the default depends on your organization's data retention policy: @@ -100860,16 +111976,13 @@ puts(compacted_response) - `effort: ReasoningEffort` - Constrains effort on reasoning for - [reasoning models](https://platform.openai.com/docs/guides/reasoning). - Currently supported values are `none`, `minimal`, `low`, `medium`, `high`, and `xhigh`. Reducing - reasoning effort can result in faster responses and fewer tokens used - on reasoning in a response. - - - `gpt-5.1` defaults to `none`, which does not perform reasoning. The supported reasoning values for `gpt-5.1` are `none`, `low`, `medium`, and `high`. Tool calls are supported for all reasoning values in gpt-5.1. - - All models before `gpt-5.1` default to `medium` reasoning effort, and do not support `none`. - - The `gpt-5-pro` model defaults to (and only supports) `high` reasoning effort. - - `xhigh` is supported for all models after `gpt-5.1-codex-max`. + Constrains effort on reasoning for reasoning models. Currently supported + values are `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max`. + Reducing reasoning effort can result in faster responses and fewer tokens + used on reasoning in a response. Not all reasoning models support every + value. See the + [reasoning guide](https://platform.openai.com/docs/guides/reasoning) + for model-specific support. - `:none` @@ -100883,6 +111996,8 @@ puts(compacted_response) - `:xhigh` + - `:max` + - `generate_summary: :auto | :concise | :detailed` **Deprecated:** use `summary` instead. @@ -100897,6 +112012,24 @@ puts(compacted_response) - `:detailed` + - `mode: String | :standard | :pro` + + Controls the reasoning execution mode for the request. + + When returned on a response, this is the effective execution mode. + + - `String = String` + + - `Mode = :standard | :pro` + + Controls the reasoning execution mode for the request. + + When returned on a response, this is the effective execution mode. + + - `:standard` + + - `:pro` + - `summary: :auto | :concise | :detailed` A summary of the reasoning performed by the model. This can be @@ -101061,7 +112194,7 @@ puts(compacted_response) - `:high` - - `tool_choice: ToolChoiceOptions | ToolChoiceAllowed | ToolChoiceTypes | 5 more` + - `tool_choice: ToolChoiceOptions | ToolChoiceAllowed | ToolChoiceTypes | 6 more` How the model should select which tool (or tools) to use when generating a response. See the `tools` parameter to see how to specify which tools @@ -101203,6 +112336,14 @@ puts(compacted_response) - `:custom` + - `class SpecificProgrammaticToolCallingParam` + + - `type: :programmatic_tool_calling` + + The tool to call. Always `programmatic_tool_calling`. + + - `:programmatic_tool_calling` + - `class ToolChoiceApplyPatch` Forces the model to call the apply_patch tool when executing a tool call. @@ -101273,6 +112414,8 @@ puts(compacted_response) A tool that runs Python code to help generate a response to a prompt. + - `class ProgrammaticToolCalling` + - `class ImageGeneration` A tool that generates images using the GPT image models. @@ -101549,7 +112692,7 @@ puts(compacted_response) An error object returned when the model fails to generate a Response. - - `code: :server_error | :rate_limit_exceeded | :invalid_prompt | 15 more` + - `code: :server_error | :rate_limit_exceeded | :invalid_prompt | 16 more` The error code for the response. @@ -101559,6 +112702,8 @@ puts(compacted_response) - `:invalid_prompt` + - `:bio_policy` + - `:vector_store_timeout` - `:invalid_image` @@ -101659,6 +112804,16 @@ puts(compacted_response) - `:input_text` + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + + 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`. + + - `:explicit` + - `class ResponseInputImage` An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). @@ -101689,6 +112844,16 @@ puts(compacted_response) The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + + 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`. + + - `:explicit` + - `class ResponseInputFile` A file input to the model. @@ -101699,9 +112864,11 @@ puts(compacted_response) - `:input_file` - - `detail: :low | :high` + - `detail: :auto | :low | :high` - The detail level of the file to be sent to the model. Use `low` for the default rendering behavior, or `high` to render the file at higher quality. Defaults to `low`. + The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. + + - `:auto` - `:low` @@ -101723,6 +112890,16 @@ puts(compacted_response) The name of the file to be sent to the model. + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + + 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`. + + - `:explicit` + - `role: :user | :assistant | :system | :developer` The role of the message input. One of `user`, `assistant`, `system`, or @@ -102670,6 +113847,26 @@ puts(compacted_response) The unique ID of the function tool call. + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + - `:program` + - `namespace: String` The namespace of the function to run. @@ -102719,6 +113916,16 @@ puts(compacted_response) - `:input_text` + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + + 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`. + + - `:explicit` + - `class ResponseInputImageContent` An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) @@ -102749,6 +113956,16 @@ puts(compacted_response) The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + + 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`. + + - `:explicit` + - `class ResponseInputFileContent` A file input to the model. @@ -102759,9 +113976,11 @@ puts(compacted_response) - `:input_file` - - `detail: :low | :high` + - `detail: :auto | :low | :high` + + The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. - The detail level of the file to be sent to the model. Use `low` for the default rendering behavior, or `high` to render the file at higher quality. Defaults to `low`. + - `:auto` - `:low` @@ -102783,6 +114002,16 @@ puts(compacted_response) The name of the file to be sent to the model. + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + + 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`. + + - `:explicit` + - `type: :function_call_output` The type of the function tool call output. Always `function_call_output`. @@ -102793,6 +114022,30 @@ puts(compacted_response) The unique ID of the function tool call output. Populated when this item is returned via API. + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + The caller type. Always `direct`. + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + The caller type. Always `program`. + + - `:program` + - `status: :in_progress | :completed | :incomplete` The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. @@ -102861,7 +114114,7 @@ puts(compacted_response) - `strict: bool` - Whether to enforce strict parameter validation. Default `true`. + Whether strict parameter validation is enforced for this function tool. - `type: :function` @@ -102869,6 +114122,14 @@ puts(compacted_response) - `:function` + - `allowed_callers: Array[:direct | :programmatic]` + + The tool invocation context(s). + + - `:direct` + + - `:programmatic` + - `defer_loading: bool` Whether this function is deferred and loaded via tool search. @@ -102877,6 +114138,10 @@ puts(compacted_response) A description of the function. Used by the model to determine whether or not to call the function. + - `output_schema: Hash[Symbol, untyped]` + + A JSON schema object describing the JSON value encoded in string outputs for this function. + - `class FileSearchTool` A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). @@ -102932,7 +114197,7 @@ puts(compacted_response) - `:nin` - - `value: String | Float | bool | Array[String | Float]` + - `value: String | Float | bool | Array[untyped]` The value to compare against the attribute key; supports string, number, or boolean types. @@ -102942,11 +114207,7 @@ puts(compacted_response) - `UnionMember2 = bool` - - `UnionMember3 = Array[String | Float]` - - - `String = String` - - - `Float = Float` + - `UnionMember3 = Array[untyped]` - `class CompoundFilter` @@ -103119,6 +114380,14 @@ puts(compacted_response) - `:mcp` + - `allowed_callers: Array[:direct | :programmatic]` + + The tool invocation context(s). + + - `:direct` + + - `:programmatic` + - `allowed_tools: Array[String] | McpToolFilter{ read_only, tool_names}` List of allowed tool names or a filter object. @@ -103337,6 +114606,22 @@ puts(compacted_response) - `:code_interpreter` + - `allowed_callers: Array[:direct | :programmatic]` + + The tool invocation context(s). + + - `:direct` + + - `:programmatic` + + - `class ProgrammaticToolCalling` + + - `type: :programmatic_tool_calling` + + The type of the tool. Always `programmatic_tool_calling`. + + - `:programmatic_tool_calling` + - `class ImageGeneration` A tool that generates images using the GPT image models. @@ -103500,6 +114785,14 @@ puts(compacted_response) - `:shell` + - `allowed_callers: Array[:direct | :programmatic]` + + The tool invocation context(s). + + - `:direct` + + - `:programmatic` + - `environment: ContainerAuto | LocalEnvironment | ContainerReference` - `class ContainerAuto` @@ -103640,6 +114933,14 @@ puts(compacted_response) - `:custom` + - `allowed_callers: Array[:direct | :programmatic]` + + The tool invocation context(s). + + - `:direct` + + - `:programmatic` + - `defer_loading: bool` Whether this tool should be deferred and discovered via tool search. @@ -103696,7 +114997,7 @@ puts(compacted_response) The namespace name used in tool calls (for example, `crm`). - - `tools: Array[Function{ name, type, defer_loading, 3 more} | CustomTool]` + - `tools: Array[Function{ name, type, allowed_callers, 5 more} | CustomTool]` The function/custom tools available inside this namespace. @@ -103708,16 +115009,30 @@ puts(compacted_response) - `:function` + - `allowed_callers: Array[:direct | :programmatic]` + + The tool invocation context(s). + + - `:direct` + + - `:programmatic` + - `defer_loading: bool` Whether this function should be deferred and discovered via tool search. - `description: String` + - `output_schema: Hash[Symbol, untyped]` + + A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. + - `parameters: untyped` - `strict: bool` + Whether to enforce strict parameter validation. If omitted, Responses attempts to use strict validation when the schema is compatible, and falls back to non-strict validation otherwise. + - `class CustomTool` A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) @@ -103818,6 +115133,14 @@ puts(compacted_response) - `:apply_patch` + - `allowed_callers: Array[:direct | :programmatic]` + + The tool invocation context(s). + + - `:direct` + + - `:programmatic` + - `type: :tool_search_output` The item type. Always `tool_search_output`. @@ -103892,6 +115215,8 @@ puts(compacted_response) A tool that runs Python code to help generate a response to a prompt. + - `class ProgrammaticToolCalling` + - `class ImageGeneration` A tool that generates images using the GPT image models. @@ -104232,6 +115557,30 @@ puts(compacted_response) The unique ID of the shell tool call. Populated when this item is returned via API. + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + The caller type. Always `direct`. + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + The caller type. Always `program`. + + - `:program` + - `environment: LocalEnvironment | ContainerReference` The environment to execute the shell commands in. @@ -104308,6 +115657,30 @@ puts(compacted_response) The unique ID of the shell tool call output. Populated when this item is returned via API. + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + The caller type. Always `direct`. + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + The caller type. Always `program`. + + - `:program` + - `max_output_length: Integer` The maximum number of UTF-8 characters captured for this shell call's combined output. @@ -104402,6 +115775,30 @@ puts(compacted_response) The unique ID of the apply patch tool call. Populated when this item is returned via API. + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + The caller type. Always `direct`. + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + The caller type. Always `program`. + + - `:program` + - `class ApplyPatchCallOutput` The streamed output emitted by an apply patch tool call. @@ -104428,6 +115825,30 @@ puts(compacted_response) The unique ID of the apply patch tool call output. Populated when this item is returned via API. + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + The caller type. Always `direct`. + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + The caller type. Always `program`. + + - `:program` + - `output: String` Optional human-readable log text from the apply patch tool (e.g., patch results or errors). @@ -104622,6 +116043,30 @@ puts(compacted_response) The unique ID of the custom tool call output in the OpenAI platform. + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + The caller type. Always `direct`. + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + The caller type. Always `program`. + + - `:program` + - `class ResponseCustomToolCall` A call to a custom tool created by the model. @@ -104648,6 +116093,26 @@ puts(compacted_response) The unique ID of the custom tool call in the OpenAI platform. + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + - `:program` + - `namespace: String` The namespace of the custom tool being called. @@ -104676,6 +116141,58 @@ puts(compacted_response) - `:item_reference` + - `class Program` + + - `id: String` + + The unique ID of this program item. + + - `call_id: String` + + The stable call ID of the program item. + + - `code: String` + + The JavaScript source executed by programmatic tool calling. + + - `fingerprint: String` + + Opaque program replay fingerprint that must be round-tripped. + + - `type: :program` + + The item type. Always `program`. + + - `:program` + + - `class ProgramOutput` + + - `id: String` + + The unique ID of this program output item. + + - `call_id: String` + + The call ID of the program item. + + - `result: String` + + The result produced by the program item. + + - `status: :completed | :incomplete` + + The terminal status of the program output. + + - `:completed` + + - `:incomplete` + + - `type: :program_output` + + The item type. Always `program_output`. + + - `:program_output` + - `metadata: Metadata` Set of 16 key-value pairs that can be attached to an object. This can be @@ -104694,7 +116211,13 @@ puts(compacted_response) - `String = String` - - `ChatModel = :"gpt-5.4" | :"gpt-5.4-mini" | :"gpt-5.4-nano" | 75 more` + - `ChatModel = :"gpt-5.6-sol" | :"gpt-5.6-terra" | :"gpt-5.6-luna" | 78 more` + + - `:"gpt-5.6-sol"` + + - `:"gpt-5.6-terra"` + + - `:"gpt-5.6-luna"` - `:"gpt-5.4"` @@ -104965,6 +116488,30 @@ puts(compacted_response) - `:function_call_output` + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + The caller type. Always `direct`. + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + The caller type. Always `program`. + + - `:program` + - `created_by: String` The identifier of the actor that created the item. @@ -105040,6 +116587,58 @@ puts(compacted_response) for subsequent turns of a conversation if you are manually [managing context](https://platform.openai.com/docs/guides/conversation-state). + - `class Program` + + - `id: String` + + The unique ID of the program item. + + - `call_id: String` + + The stable call ID of the program item. + + - `code: String` + + The JavaScript source executed by programmatic tool calling. + + - `fingerprint: String` + + Opaque program replay fingerprint that must be round-tripped. + + - `type: :program` + + The type of the item. Always `program`. + + - `:program` + + - `class ProgramOutput` + + - `id: String` + + The unique ID of the program output item. + + - `call_id: String` + + The call ID of the program item. + + - `result: String` + + The result produced by the program item. + + - `status: :completed | :incomplete` + + The terminal status of the program output item. + + - `:completed` + + - `:incomplete` + + - `type: :program_output` + + The type of the item. Always `program_output`. + + - `:program_output` + - `class ResponseToolSearchCall` - `id: String` @@ -105144,6 +116743,8 @@ puts(compacted_response) A tool that runs Python code to help generate a response to a prompt. + - `class ProgrammaticToolCalling` + - `class ImageGeneration` A tool that generates images using the GPT image models. @@ -105246,6 +116847,8 @@ puts(compacted_response) A tool that runs Python code to help generate a response to a prompt. + - `class ProgrammaticToolCalling` + - `class ImageGeneration` A tool that generates images using the GPT image models. @@ -105494,6 +117097,26 @@ puts(compacted_response) - `:shell_call` + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + - `:program` + - `created_by: String` The ID of the entity that created this tool call. @@ -105574,6 +117197,26 @@ puts(compacted_response) - `:shell_call_output` + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + - `:program` + - `created_by: String` The identifier of the actor that created the item. @@ -105658,6 +117301,26 @@ puts(compacted_response) - `:apply_patch_call` + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + - `:program` + - `created_by: String` The ID of the entity that created this tool call. @@ -105688,6 +117351,26 @@ puts(compacted_response) - `:apply_patch_call_output` + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + - `:program` + - `created_by: String` The ID of the entity that created this tool call output. @@ -105879,7 +117562,7 @@ puts(compacted_response) What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. We generally recommend altering this or `top_p` but not both. - - `tool_choice: ToolChoiceOptions | ToolChoiceAllowed | ToolChoiceTypes | 5 more` + - `tool_choice: ToolChoiceOptions | ToolChoiceAllowed | ToolChoiceTypes | 6 more` How the model should select which tool (or tools) to use when generating a response. See the `tools` parameter to see how to specify which tools @@ -106021,6 +117704,14 @@ puts(compacted_response) - `:custom` + - `class SpecificProgrammaticToolCallingParam` + + - `type: :programmatic_tool_calling` + + The tool to call. Always `programmatic_tool_calling`. + + - `:programmatic_tool_calling` + - `class ToolChoiceApplyPatch` Forces the model to call the apply_patch tool when executing a tool call. @@ -106091,6 +117782,8 @@ puts(compacted_response) A tool that runs Python code to help generate a response to a prompt. + - `class ProgrammaticToolCalling` + - `class ImageGeneration` A tool that generates images using the GPT image models. @@ -106317,9 +118010,32 @@ puts(compacted_response) Used by OpenAI to cache responses for similar requests to optimize your cache hit rates. Replaces the `user` field. [Learn more](https://platform.openai.com/docs/guides/prompt-caching). + - `prompt_cache_options: PromptCacheOptions{ mode, ttl}` + + The prompt-caching options that were applied to the response. Supported for `gpt-5.6` and later models. + + - `mode: :implicit | :explicit` + + Whether implicit prompt-cache breakpoints were enabled. + + - `:implicit` + + - `:explicit` + + - `ttl: :"30m"` + + The minimum lifetime applied to each cache breakpoint. + + - `:"30m"` + - `prompt_cache_retention: :in_memory | :"24h"` + Deprecated. Use `prompt_cache_options.ttl` instead. + The retention policy for the prompt cache. Set to `24h` to enable extended prompt caching, which keeps cached prefixes active for longer, up to a maximum of 24 hours. [Learn more](https://platform.openai.com/docs/guides/prompt-caching#prompt-cache-retention). + This field expresses a maximum retention policy, while + `prompt_cache_options.ttl` expresses a minimum cache lifetime. The two + fields are independent and do not interact. For `gpt-5.5`, `gpt-5.5-pro`, and future models, only `24h` is supported. For older models that support both `in_memory` and `24h`, the default depends on your organization's data retention policy: @@ -106352,16 +118068,13 @@ puts(compacted_response) - `effort: ReasoningEffort` - Constrains effort on reasoning for - [reasoning models](https://platform.openai.com/docs/guides/reasoning). - Currently supported values are `none`, `minimal`, `low`, `medium`, `high`, and `xhigh`. Reducing - reasoning effort can result in faster responses and fewer tokens used - on reasoning in a response. - - - `gpt-5.1` defaults to `none`, which does not perform reasoning. The supported reasoning values for `gpt-5.1` are `none`, `low`, `medium`, and `high`. Tool calls are supported for all reasoning values in gpt-5.1. - - All models before `gpt-5.1` default to `medium` reasoning effort, and do not support `none`. - - The `gpt-5-pro` model defaults to (and only supports) `high` reasoning effort. - - `xhigh` is supported for all models after `gpt-5.1-codex-max`. + Constrains effort on reasoning for reasoning models. Currently supported + values are `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max`. + Reducing reasoning effort can result in faster responses and fewer tokens + used on reasoning in a response. Not all reasoning models support every + value. See the + [reasoning guide](https://platform.openai.com/docs/guides/reasoning) + for model-specific support. - `:none` @@ -106375,6 +118088,8 @@ puts(compacted_response) - `:xhigh` + - `:max` + - `generate_summary: :auto | :concise | :detailed` **Deprecated:** use `summary` instead. @@ -106389,6 +118104,24 @@ puts(compacted_response) - `:detailed` + - `mode: String | :standard | :pro` + + Controls the reasoning execution mode for the request. + + When returned on a response, this is the effective execution mode. + + - `String = String` + + - `Mode = :standard | :pro` + + Controls the reasoning execution mode for the request. + + When returned on a response, this is the effective execution mode. + + - `:standard` + + - `:pro` + - `summary: :auto | :concise | :detailed` A summary of the reasoning performed by the model. This can be @@ -106569,10 +118302,14 @@ puts(compacted_response) The number of input tokens. - - `input_tokens_details: InputTokensDetails{ cached_tokens}` + - `input_tokens_details: InputTokensDetails{ cache_write_tokens, cached_tokens}` A detailed breakdown of the input tokens. + - `cache_write_tokens: Integer` + + The number of input tokens that were written to the cache. + - `cached_tokens: Integer` The number of tokens that were retrieved from the cache. @@ -106975,6 +118712,10 @@ puts(compacted_response) for subsequent turns of a conversation if you are manually [managing context](https://platform.openai.com/docs/guides/conversation-state). + - `class Program` + + - `class ProgramOutput` + - `class ResponseToolSearchCall` - `class ResponseToolSearchOutputItem` @@ -107157,6 +118898,13 @@ puts(compacted_response) - `:"response.reasoning_summary_part.done"` + - `status: :incomplete` + + The completion status of the summary part. Omitted when the part completed + normally and set to `incomplete` when generation was interrupted. + + - `:incomplete` + - `class ResponseReasoningSummaryTextDeltaEvent` Emitted when a delta is added to a reasoning summary text. @@ -107915,7 +119663,7 @@ puts(compacted_response) ### Tool -- `Tool = FunctionTool | FileSearchTool | ComputerTool | 12 more` +- `Tool = FunctionTool | FileSearchTool | ComputerTool | 13 more` A tool that can be used to generate a response. @@ -107933,7 +119681,7 @@ puts(compacted_response) - `strict: bool` - Whether to enforce strict parameter validation. Default `true`. + Whether strict parameter validation is enforced for this function tool. - `type: :function` @@ -107941,6 +119689,14 @@ puts(compacted_response) - `:function` + - `allowed_callers: Array[:direct | :programmatic]` + + The tool invocation context(s). + + - `:direct` + + - `:programmatic` + - `defer_loading: bool` Whether this function is deferred and loaded via tool search. @@ -107949,6 +119705,10 @@ puts(compacted_response) A description of the function. Used by the model to determine whether or not to call the function. + - `output_schema: Hash[Symbol, untyped]` + + A JSON schema object describing the JSON value encoded in string outputs for this function. + - `class FileSearchTool` A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). @@ -108004,7 +119764,7 @@ puts(compacted_response) - `:nin` - - `value: String | Float | bool | Array[String | Float]` + - `value: String | Float | bool | Array[untyped]` The value to compare against the attribute key; supports string, number, or boolean types. @@ -108014,11 +119774,7 @@ puts(compacted_response) - `UnionMember2 = bool` - - `UnionMember3 = Array[String | Float]` - - - `String = String` - - - `Float = Float` + - `UnionMember3 = Array[untyped]` - `class CompoundFilter` @@ -108191,6 +119947,14 @@ puts(compacted_response) - `:mcp` + - `allowed_callers: Array[:direct | :programmatic]` + + The tool invocation context(s). + + - `:direct` + + - `:programmatic` + - `allowed_tools: Array[String] | McpToolFilter{ read_only, tool_names}` List of allowed tool names or a filter object. @@ -108409,6 +120173,22 @@ puts(compacted_response) - `:code_interpreter` + - `allowed_callers: Array[:direct | :programmatic]` + + The tool invocation context(s). + + - `:direct` + + - `:programmatic` + + - `class ProgrammaticToolCalling` + + - `type: :programmatic_tool_calling` + + The type of the tool. Always `programmatic_tool_calling`. + + - `:programmatic_tool_calling` + - `class ImageGeneration` A tool that generates images using the GPT image models. @@ -108572,6 +120352,14 @@ puts(compacted_response) - `:shell` + - `allowed_callers: Array[:direct | :programmatic]` + + The tool invocation context(s). + + - `:direct` + + - `:programmatic` + - `environment: ContainerAuto | LocalEnvironment | ContainerReference` - `class ContainerAuto` @@ -108712,6 +120500,14 @@ puts(compacted_response) - `:custom` + - `allowed_callers: Array[:direct | :programmatic]` + + The tool invocation context(s). + + - `:direct` + + - `:programmatic` + - `defer_loading: bool` Whether this tool should be deferred and discovered via tool search. @@ -108768,7 +120564,7 @@ puts(compacted_response) The namespace name used in tool calls (for example, `crm`). - - `tools: Array[Function{ name, type, defer_loading, 3 more} | CustomTool]` + - `tools: Array[Function{ name, type, allowed_callers, 5 more} | CustomTool]` The function/custom tools available inside this namespace. @@ -108780,16 +120576,30 @@ puts(compacted_response) - `:function` + - `allowed_callers: Array[:direct | :programmatic]` + + The tool invocation context(s). + + - `:direct` + + - `:programmatic` + - `defer_loading: bool` Whether this function should be deferred and discovered via tool search. - `description: String` + - `output_schema: Hash[Symbol, untyped]` + + A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. + - `parameters: untyped` - `strict: bool` + Whether to enforce strict parameter validation. If omitted, Responses attempts to use strict validation when the schema is compatible, and falls back to non-strict validation otherwise. + - `class CustomTool` A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) @@ -108890,6 +120700,14 @@ puts(compacted_response) - `:apply_patch` + - `allowed_callers: Array[:direct | :programmatic]` + + The tool invocation context(s). + + - `:direct` + + - `:programmatic` + ### Tool Choice Allowed - `class ToolChoiceAllowed` @@ -109216,7 +121034,7 @@ puts(compacted_response) **get** `/responses/{response_id}/input_items` -Returns a list of input items for a given response. +List input items ### Parameters @@ -109265,7 +121083,7 @@ Returns a list of input items for a given response. ### Returns -- `ResponseItem = ResponseInputMessageItem | ResponseOutputMessage | ResponseFileSearchToolCall | 24 more` +- `ResponseItem = ResponseInputMessageItem | ResponseOutputMessage | ResponseFileSearchToolCall | 26 more` Content item used to generate a response. @@ -109294,6 +121112,16 @@ Returns a list of input items for a given response. - `:input_text` + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + + 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`. + + - `:explicit` + - `class ResponseInputImage` An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). @@ -109324,6 +121152,16 @@ Returns a list of input items for a given response. The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + + 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`. + + - `:explicit` + - `class ResponseInputFile` A file input to the model. @@ -109334,9 +121172,11 @@ Returns a list of input items for a given response. - `:input_file` - - `detail: :low | :high` + - `detail: :auto | :low | :high` - The detail level of the file to be sent to the model. Use `low` for the default rendering behavior, or `high` to render the file at higher quality. Defaults to `low`. + The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. + + - `:auto` - `:low` @@ -109358,6 +121198,16 @@ Returns a list of input items for a given response. The name of the file to be sent to the model. + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + + 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`. + + - `:explicit` + - `role: :user | :system | :developer` The role of the message input. One of `user`, `system`, or `developer`. @@ -110320,6 +122170,30 @@ Returns a list of input items for a given response. - `:function_call_output` + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + The caller type. Always `direct`. + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + The caller type. Always `program`. + + - `:program` + - `created_by: String` The identifier of the actor that created the item. @@ -110412,7 +122286,7 @@ Returns a list of input items for a given response. - `strict: bool` - Whether to enforce strict parameter validation. Default `true`. + Whether strict parameter validation is enforced for this function tool. - `type: :function` @@ -110420,6 +122294,14 @@ Returns a list of input items for a given response. - `:function` + - `allowed_callers: Array[:direct | :programmatic]` + + The tool invocation context(s). + + - `:direct` + + - `:programmatic` + - `defer_loading: bool` Whether this function is deferred and loaded via tool search. @@ -110428,6 +122310,10 @@ Returns a list of input items for a given response. A description of the function. Used by the model to determine whether or not to call the function. + - `output_schema: Hash[Symbol, untyped]` + + A JSON schema object describing the JSON value encoded in string outputs for this function. + - `class FileSearchTool` A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). @@ -110483,7 +122369,7 @@ Returns a list of input items for a given response. - `:nin` - - `value: String | Float | bool | Array[String | Float]` + - `value: String | Float | bool | Array[untyped]` The value to compare against the attribute key; supports string, number, or boolean types. @@ -110493,11 +122379,7 @@ Returns a list of input items for a given response. - `UnionMember2 = bool` - - `UnionMember3 = Array[String | Float]` - - - `String = String` - - - `Float = Float` + - `UnionMember3 = Array[untyped]` - `class CompoundFilter` @@ -110670,6 +122552,14 @@ Returns a list of input items for a given response. - `:mcp` + - `allowed_callers: Array[:direct | :programmatic]` + + The tool invocation context(s). + + - `:direct` + + - `:programmatic` + - `allowed_tools: Array[String] | McpToolFilter{ read_only, tool_names}` List of allowed tool names or a filter object. @@ -110888,6 +122778,22 @@ Returns a list of input items for a given response. - `:code_interpreter` + - `allowed_callers: Array[:direct | :programmatic]` + + The tool invocation context(s). + + - `:direct` + + - `:programmatic` + + - `class ProgrammaticToolCalling` + + - `type: :programmatic_tool_calling` + + The type of the tool. Always `programmatic_tool_calling`. + + - `:programmatic_tool_calling` + - `class ImageGeneration` A tool that generates images using the GPT image models. @@ -111051,6 +122957,14 @@ Returns a list of input items for a given response. - `:shell` + - `allowed_callers: Array[:direct | :programmatic]` + + The tool invocation context(s). + + - `:direct` + + - `:programmatic` + - `environment: ContainerAuto | LocalEnvironment | ContainerReference` - `class ContainerAuto` @@ -111191,6 +123105,14 @@ Returns a list of input items for a given response. - `:custom` + - `allowed_callers: Array[:direct | :programmatic]` + + The tool invocation context(s). + + - `:direct` + + - `:programmatic` + - `defer_loading: bool` Whether this tool should be deferred and discovered via tool search. @@ -111247,7 +123169,7 @@ Returns a list of input items for a given response. The namespace name used in tool calls (for example, `crm`). - - `tools: Array[Function{ name, type, defer_loading, 3 more} | CustomTool]` + - `tools: Array[Function{ name, type, allowed_callers, 5 more} | CustomTool]` The function/custom tools available inside this namespace. @@ -111259,16 +123181,30 @@ Returns a list of input items for a given response. - `:function` + - `allowed_callers: Array[:direct | :programmatic]` + + The tool invocation context(s). + + - `:direct` + + - `:programmatic` + - `defer_loading: bool` Whether this function should be deferred and discovered via tool search. - `description: String` + - `output_schema: Hash[Symbol, untyped]` + + A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. + - `parameters: untyped` - `strict: bool` + Whether to enforce strict parameter validation. If omitted, Responses attempts to use strict validation when the schema is compatible, and falls back to non-strict validation otherwise. + - `class CustomTool` A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) @@ -111369,6 +123305,14 @@ Returns a list of input items for a given response. - `:apply_patch` + - `allowed_callers: Array[:direct | :programmatic]` + + The tool invocation context(s). + + - `:direct` + + - `:programmatic` + - `type: :tool_search_output` The type of the item. Always `tool_search_output`. @@ -111439,6 +123383,8 @@ Returns a list of input items for a given response. A tool that runs Python code to help generate a response to a prompt. + - `class ProgrammaticToolCalling` + - `class ImageGeneration` A tool that generates images using the GPT image models. @@ -111538,6 +123484,58 @@ Returns a list of input items for a given response. - `:incomplete` + - `class Program` + + - `id: String` + + The unique ID of the program item. + + - `call_id: String` + + The stable call ID of the program item. + + - `code: String` + + The JavaScript source executed by programmatic tool calling. + + - `fingerprint: String` + + Opaque program replay fingerprint that must be round-tripped. + + - `type: :program` + + The type of the item. Always `program`. + + - `:program` + + - `class ProgramOutput` + + - `id: String` + + The unique ID of the program output item. + + - `call_id: String` + + The call ID of the program item. + + - `result: String` + + The result produced by the program item. + + - `status: :completed | :incomplete` + + The terminal status of the program output item. + + - `:completed` + + - `:incomplete` + + - `type: :program_output` + + The type of the item. Always `program_output`. + + - `:program_output` + - `class ResponseCompactionItem` A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). @@ -111813,6 +123811,26 @@ Returns a list of input items for a given response. - `:shell_call` + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + - `:program` + - `created_by: String` The ID of the entity that created this tool call. @@ -111893,6 +123911,26 @@ Returns a list of input items for a given response. - `:shell_call_output` + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + - `:program` + - `created_by: String` The identifier of the actor that created the item. @@ -111977,6 +124015,26 @@ Returns a list of input items for a given response. - `:apply_patch_call` + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + - `:program` + - `created_by: String` The ID of the entity that created this tool call. @@ -112007,6 +124065,26 @@ Returns a list of input items for a given response. - `:apply_patch_call_output` + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + - `:program` + - `created_by: String` The ID of the entity that created this tool call output. @@ -112230,7 +124308,10 @@ puts(page) "content": [ { "text": "text", - "type": "input_text" + "type": "input_text", + "prompt_cache_breakpoint": { + "mode": "explicit" + } } ], "role": "user", @@ -112282,6 +124363,16 @@ puts(page) - `:input_text` + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + + 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`. + + - `:explicit` + - `class ResponseInputImage` An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). @@ -112312,6 +124403,16 @@ puts(page) The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + + 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`. + + - `:explicit` + - `class ResponseInputFile` A file input to the model. @@ -112322,9 +124423,11 @@ puts(page) - `:input_file` - - `detail: :low | :high` + - `detail: :auto | :low | :high` - The detail level of the file to be sent to the model. Use `low` for the default rendering behavior, or `high` to render the file at higher quality. Defaults to `low`. + The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. + + - `:auto` - `:low` @@ -112346,6 +124449,16 @@ puts(page) The name of the file to be sent to the model. + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + + 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`. + + - `:explicit` + - `role: :user | :system | :developer` The role of the message input. One of `user`, `system`, or `developer`. @@ -113308,6 +125421,30 @@ puts(page) - `:function_call_output` + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + The caller type. Always `direct`. + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + The caller type. Always `program`. + + - `:program` + - `created_by: String` The identifier of the actor that created the item. @@ -113400,7 +125537,7 @@ puts(page) - `strict: bool` - Whether to enforce strict parameter validation. Default `true`. + Whether strict parameter validation is enforced for this function tool. - `type: :function` @@ -113408,6 +125545,14 @@ puts(page) - `:function` + - `allowed_callers: Array[:direct | :programmatic]` + + The tool invocation context(s). + + - `:direct` + + - `:programmatic` + - `defer_loading: bool` Whether this function is deferred and loaded via tool search. @@ -113416,6 +125561,10 @@ puts(page) A description of the function. Used by the model to determine whether or not to call the function. + - `output_schema: Hash[Symbol, untyped]` + + A JSON schema object describing the JSON value encoded in string outputs for this function. + - `class FileSearchTool` A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). @@ -113471,7 +125620,7 @@ puts(page) - `:nin` - - `value: String | Float | bool | Array[String | Float]` + - `value: String | Float | bool | Array[untyped]` The value to compare against the attribute key; supports string, number, or boolean types. @@ -113481,11 +125630,7 @@ puts(page) - `UnionMember2 = bool` - - `UnionMember3 = Array[String | Float]` - - - `String = String` - - - `Float = Float` + - `UnionMember3 = Array[untyped]` - `class CompoundFilter` @@ -113658,6 +125803,14 @@ puts(page) - `:mcp` + - `allowed_callers: Array[:direct | :programmatic]` + + The tool invocation context(s). + + - `:direct` + + - `:programmatic` + - `allowed_tools: Array[String] | McpToolFilter{ read_only, tool_names}` List of allowed tool names or a filter object. @@ -113876,6 +126029,22 @@ puts(page) - `:code_interpreter` + - `allowed_callers: Array[:direct | :programmatic]` + + The tool invocation context(s). + + - `:direct` + + - `:programmatic` + + - `class ProgrammaticToolCalling` + + - `type: :programmatic_tool_calling` + + The type of the tool. Always `programmatic_tool_calling`. + + - `:programmatic_tool_calling` + - `class ImageGeneration` A tool that generates images using the GPT image models. @@ -114039,6 +126208,14 @@ puts(page) - `:shell` + - `allowed_callers: Array[:direct | :programmatic]` + + The tool invocation context(s). + + - `:direct` + + - `:programmatic` + - `environment: ContainerAuto | LocalEnvironment | ContainerReference` - `class ContainerAuto` @@ -114179,6 +126356,14 @@ puts(page) - `:custom` + - `allowed_callers: Array[:direct | :programmatic]` + + The tool invocation context(s). + + - `:direct` + + - `:programmatic` + - `defer_loading: bool` Whether this tool should be deferred and discovered via tool search. @@ -114235,7 +126420,7 @@ puts(page) The namespace name used in tool calls (for example, `crm`). - - `tools: Array[Function{ name, type, defer_loading, 3 more} | CustomTool]` + - `tools: Array[Function{ name, type, allowed_callers, 5 more} | CustomTool]` The function/custom tools available inside this namespace. @@ -114247,16 +126432,30 @@ puts(page) - `:function` + - `allowed_callers: Array[:direct | :programmatic]` + + The tool invocation context(s). + + - `:direct` + + - `:programmatic` + - `defer_loading: bool` Whether this function should be deferred and discovered via tool search. - `description: String` + - `output_schema: Hash[Symbol, untyped]` + + A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. + - `parameters: untyped` - `strict: bool` + Whether to enforce strict parameter validation. If omitted, Responses attempts to use strict validation when the schema is compatible, and falls back to non-strict validation otherwise. + - `class CustomTool` A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) @@ -114357,6 +126556,14 @@ puts(page) - `:apply_patch` + - `allowed_callers: Array[:direct | :programmatic]` + + The tool invocation context(s). + + - `:direct` + + - `:programmatic` + - `type: :tool_search_output` The type of the item. Always `tool_search_output`. @@ -114427,6 +126634,8 @@ puts(page) A tool that runs Python code to help generate a response to a prompt. + - `class ProgrammaticToolCalling` + - `class ImageGeneration` A tool that generates images using the GPT image models. @@ -114526,6 +126735,58 @@ puts(page) - `:incomplete` + - `class Program` + + - `id: String` + + The unique ID of the program item. + + - `call_id: String` + + The stable call ID of the program item. + + - `code: String` + + The JavaScript source executed by programmatic tool calling. + + - `fingerprint: String` + + Opaque program replay fingerprint that must be round-tripped. + + - `type: :program` + + The type of the item. Always `program`. + + - `:program` + + - `class ProgramOutput` + + - `id: String` + + The unique ID of the program output item. + + - `call_id: String` + + The call ID of the program item. + + - `result: String` + + The result produced by the program item. + + - `status: :completed | :incomplete` + + The terminal status of the program output item. + + - `:completed` + + - `:incomplete` + + - `type: :program_output` + + The type of the item. Always `program_output`. + + - `:program_output` + - `class ResponseCompactionItem` A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). @@ -114801,6 +127062,26 @@ puts(page) - `:shell_call` + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + - `:program` + - `created_by: String` The ID of the entity that created this tool call. @@ -114881,6 +127162,26 @@ puts(page) - `:shell_call_output` + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + - `:program` + - `created_by: String` The identifier of the actor that created the item. @@ -114965,6 +127266,26 @@ puts(page) - `:apply_patch_call` + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + - `:program` + - `created_by: String` The ID of the entity that created this tool call. @@ -114995,6 +127316,26 @@ puts(page) - `:apply_patch_call_output` + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + - `:program` + - `created_by: String` The ID of the entity that created this tool call output. @@ -115222,9 +127563,7 @@ puts(page) **post** `/responses/input_tokens` -Returns input token counts of the request. - -Returns an object with `object` set to `response.input_tokens` and an `input_tokens` count. +Get input token counts ### Parameters @@ -115293,6 +127632,16 @@ Returns an object with `object` set to `response.input_tokens` and an `input_tok - `:input_text` + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + + 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`. + + - `:explicit` + - `class ResponseInputImage` An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). @@ -115323,6 +127672,16 @@ Returns an object with `object` set to `response.input_tokens` and an `input_tok The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + + 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`. + + - `:explicit` + - `class ResponseInputFile` A file input to the model. @@ -115333,9 +127692,11 @@ Returns an object with `object` set to `response.input_tokens` and an `input_tok - `:input_file` - - `detail: :low | :high` + - `detail: :auto | :low | :high` + + The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. - The detail level of the file to be sent to the model. Use `low` for the default rendering behavior, or `high` to render the file at higher quality. Defaults to `low`. + - `:auto` - `:low` @@ -115357,6 +127718,16 @@ Returns an object with `object` set to `response.input_tokens` and an `input_tok The name of the file to be sent to the model. + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + + 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`. + + - `:explicit` + - `role: :user | :assistant | :system | :developer` The role of the message input. One of `user`, `assistant`, `system`, or @@ -116304,6 +128675,26 @@ Returns an object with `object` set to `response.input_tokens` and an `input_tok The unique ID of the function tool call. + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + - `:program` + - `namespace: String` The namespace of the function to run. @@ -116353,6 +128744,16 @@ Returns an object with `object` set to `response.input_tokens` and an `input_tok - `:input_text` + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + + 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`. + + - `:explicit` + - `class ResponseInputImageContent` An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) @@ -116383,6 +128784,16 @@ Returns an object with `object` set to `response.input_tokens` and an `input_tok The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + + 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`. + + - `:explicit` + - `class ResponseInputFileContent` A file input to the model. @@ -116393,9 +128804,11 @@ Returns an object with `object` set to `response.input_tokens` and an `input_tok - `:input_file` - - `detail: :low | :high` + - `detail: :auto | :low | :high` + + The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. - The detail level of the file to be sent to the model. Use `low` for the default rendering behavior, or `high` to render the file at higher quality. Defaults to `low`. + - `:auto` - `:low` @@ -116417,6 +128830,16 @@ Returns an object with `object` set to `response.input_tokens` and an `input_tok The name of the file to be sent to the model. + - `prompt_cache_breakpoint: PromptCacheBreakpoint{ mode}` + + 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`. + + - `:explicit` + - `type: :function_call_output` The type of the function tool call output. Always `function_call_output`. @@ -116427,6 +128850,30 @@ Returns an object with `object` set to `response.input_tokens` and an `input_tok The unique ID of the function tool call output. Populated when this item is returned via API. + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + The caller type. Always `direct`. + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + The caller type. Always `program`. + + - `:program` + - `status: :in_progress | :completed | :incomplete` The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. @@ -116495,7 +128942,7 @@ Returns an object with `object` set to `response.input_tokens` and an `input_tok - `strict: bool` - Whether to enforce strict parameter validation. Default `true`. + Whether strict parameter validation is enforced for this function tool. - `type: :function` @@ -116503,6 +128950,14 @@ Returns an object with `object` set to `response.input_tokens` and an `input_tok - `:function` + - `allowed_callers: Array[:direct | :programmatic]` + + The tool invocation context(s). + + - `:direct` + + - `:programmatic` + - `defer_loading: bool` Whether this function is deferred and loaded via tool search. @@ -116511,6 +128966,10 @@ Returns an object with `object` set to `response.input_tokens` and an `input_tok A description of the function. Used by the model to determine whether or not to call the function. + - `output_schema: Hash[Symbol, untyped]` + + A JSON schema object describing the JSON value encoded in string outputs for this function. + - `class FileSearchTool` A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). @@ -116566,7 +129025,7 @@ Returns an object with `object` set to `response.input_tokens` and an `input_tok - `:nin` - - `value: String | Float | bool | Array[String | Float]` + - `value: String | Float | bool | Array[untyped]` The value to compare against the attribute key; supports string, number, or boolean types. @@ -116576,11 +129035,7 @@ Returns an object with `object` set to `response.input_tokens` and an `input_tok - `UnionMember2 = bool` - - `UnionMember3 = Array[String | Float]` - - - `String = String` - - - `Float = Float` + - `UnionMember3 = Array[untyped]` - `class CompoundFilter` @@ -116753,6 +129208,14 @@ Returns an object with `object` set to `response.input_tokens` and an `input_tok - `:mcp` + - `allowed_callers: Array[:direct | :programmatic]` + + The tool invocation context(s). + + - `:direct` + + - `:programmatic` + - `allowed_tools: Array[String] | McpToolFilter{ read_only, tool_names}` List of allowed tool names or a filter object. @@ -116971,6 +129434,22 @@ Returns an object with `object` set to `response.input_tokens` and an `input_tok - `:code_interpreter` + - `allowed_callers: Array[:direct | :programmatic]` + + The tool invocation context(s). + + - `:direct` + + - `:programmatic` + + - `class ProgrammaticToolCalling` + + - `type: :programmatic_tool_calling` + + The type of the tool. Always `programmatic_tool_calling`. + + - `:programmatic_tool_calling` + - `class ImageGeneration` A tool that generates images using the GPT image models. @@ -117134,6 +129613,14 @@ Returns an object with `object` set to `response.input_tokens` and an `input_tok - `:shell` + - `allowed_callers: Array[:direct | :programmatic]` + + The tool invocation context(s). + + - `:direct` + + - `:programmatic` + - `environment: ContainerAuto | LocalEnvironment | ContainerReference` - `class ContainerAuto` @@ -117274,6 +129761,14 @@ Returns an object with `object` set to `response.input_tokens` and an `input_tok - `:custom` + - `allowed_callers: Array[:direct | :programmatic]` + + The tool invocation context(s). + + - `:direct` + + - `:programmatic` + - `defer_loading: bool` Whether this tool should be deferred and discovered via tool search. @@ -117330,7 +129825,7 @@ Returns an object with `object` set to `response.input_tokens` and an `input_tok The namespace name used in tool calls (for example, `crm`). - - `tools: Array[Function{ name, type, defer_loading, 3 more} | CustomTool]` + - `tools: Array[Function{ name, type, allowed_callers, 5 more} | CustomTool]` The function/custom tools available inside this namespace. @@ -117342,16 +129837,30 @@ Returns an object with `object` set to `response.input_tokens` and an `input_tok - `:function` + - `allowed_callers: Array[:direct | :programmatic]` + + The tool invocation context(s). + + - `:direct` + + - `:programmatic` + - `defer_loading: bool` Whether this function should be deferred and discovered via tool search. - `description: String` + - `output_schema: Hash[Symbol, untyped]` + + A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. + - `parameters: untyped` - `strict: bool` + Whether to enforce strict parameter validation. If omitted, Responses attempts to use strict validation when the schema is compatible, and falls back to non-strict validation otherwise. + - `class CustomTool` A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) @@ -117452,6 +129961,14 @@ Returns an object with `object` set to `response.input_tokens` and an `input_tok - `:apply_patch` + - `allowed_callers: Array[:direct | :programmatic]` + + The tool invocation context(s). + + - `:direct` + + - `:programmatic` + - `type: :tool_search_output` The item type. Always `tool_search_output`. @@ -117526,6 +130043,8 @@ Returns an object with `object` set to `response.input_tokens` and an `input_tok A tool that runs Python code to help generate a response to a prompt. + - `class ProgrammaticToolCalling` + - `class ImageGeneration` A tool that generates images using the GPT image models. @@ -117866,6 +130385,30 @@ Returns an object with `object` set to `response.input_tokens` and an `input_tok The unique ID of the shell tool call. Populated when this item is returned via API. + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + The caller type. Always `direct`. + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + The caller type. Always `program`. + + - `:program` + - `environment: LocalEnvironment | ContainerReference` The environment to execute the shell commands in. @@ -117942,6 +130485,30 @@ Returns an object with `object` set to `response.input_tokens` and an `input_tok The unique ID of the shell tool call output. Populated when this item is returned via API. + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + The caller type. Always `direct`. + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + The caller type. Always `program`. + + - `:program` + - `max_output_length: Integer` The maximum number of UTF-8 characters captured for this shell call's combined output. @@ -118036,6 +130603,30 @@ Returns an object with `object` set to `response.input_tokens` and an `input_tok The unique ID of the apply patch tool call. Populated when this item is returned via API. + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + The caller type. Always `direct`. + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + The caller type. Always `program`. + + - `:program` + - `class ApplyPatchCallOutput` The streamed output emitted by an apply patch tool call. @@ -118062,6 +130653,30 @@ Returns an object with `object` set to `response.input_tokens` and an `input_tok The unique ID of the apply patch tool call output. Populated when this item is returned via API. + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + The caller type. Always `direct`. + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + The caller type. Always `program`. + + - `:program` + - `output: String` Optional human-readable log text from the apply patch tool (e.g., patch results or errors). @@ -118256,6 +130871,30 @@ Returns an object with `object` set to `response.input_tokens` and an `input_tok The unique ID of the custom tool call output in the OpenAI platform. + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + The caller type. Always `direct`. + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + The caller type. Always `program`. + + - `:program` + - `class ResponseCustomToolCall` A call to a custom tool created by the model. @@ -118282,6 +130921,26 @@ Returns an object with `object` set to `response.input_tokens` and an `input_tok The unique ID of the custom tool call in the OpenAI platform. + - `caller_: Direct{ type} | Program{ caller_id, type}` + + The execution context that produced this tool call. + + - `class Direct` + + - `type: :direct` + + - `:direct` + + - `class Program` + + - `caller_id: String` + + The call ID of the program item that produced this tool call. + + - `type: :program` + + - `:program` + - `namespace: String` The namespace of the custom tool being called. @@ -118310,6 +130969,58 @@ Returns an object with `object` set to `response.input_tokens` and an `input_tok - `:item_reference` + - `class Program` + + - `id: String` + + The unique ID of this program item. + + - `call_id: String` + + The stable call ID of the program item. + + - `code: String` + + The JavaScript source executed by programmatic tool calling. + + - `fingerprint: String` + + Opaque program replay fingerprint that must be round-tripped. + + - `type: :program` + + The item type. Always `program`. + + - `:program` + + - `class ProgramOutput` + + - `id: String` + + The unique ID of this program output item. + + - `call_id: String` + + The call ID of the program item. + + - `result: String` + + The result produced by the program item. + + - `status: :completed | :incomplete` + + The terminal status of the program output. + + - `:completed` + + - `:incomplete` + + - `type: :program_output` + + The item type. Always `program_output`. + + - `:program_output` + - `instructions: String` A system (or developer) message inserted into the model's context. @@ -118359,16 +131070,13 @@ Returns an object with `object` set to `response.input_tokens` and an `input_tok - `effort: ReasoningEffort` - Constrains effort on reasoning for - [reasoning models](https://platform.openai.com/docs/guides/reasoning). - Currently supported values are `none`, `minimal`, `low`, `medium`, `high`, and `xhigh`. Reducing - reasoning effort can result in faster responses and fewer tokens used - on reasoning in a response. - - - `gpt-5.1` defaults to `none`, which does not perform reasoning. The supported reasoning values for `gpt-5.1` are `none`, `low`, `medium`, and `high`. Tool calls are supported for all reasoning values in gpt-5.1. - - All models before `gpt-5.1` default to `medium` reasoning effort, and do not support `none`. - - The `gpt-5-pro` model defaults to (and only supports) `high` reasoning effort. - - `xhigh` is supported for all models after `gpt-5.1-codex-max`. + Constrains effort on reasoning for reasoning models. Currently supported + values are `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max`. + Reducing reasoning effort can result in faster responses and fewer tokens + used on reasoning in a response. Not all reasoning models support every + value. See the + [reasoning guide](https://platform.openai.com/docs/guides/reasoning) + for model-specific support. - `:none` @@ -118382,6 +131090,8 @@ Returns an object with `object` set to `response.input_tokens` and an `input_tok - `:xhigh` + - `:max` + - `generate_summary: :auto | :concise | :detailed` **Deprecated:** use `summary` instead. @@ -118396,6 +131106,24 @@ Returns an object with `object` set to `response.input_tokens` and an `input_tok - `:detailed` + - `mode: String | :standard | :pro` + + Controls the reasoning execution mode for the request. + + When returned on a response, this is the effective execution mode. + + - `String = String` + + - `Mode = :standard | :pro` + + Controls the reasoning execution mode for the request. + + When returned on a response, this is the effective execution mode. + + - `:standard` + + - `:pro` + - `summary: :auto | :concise | :detailed` A summary of the reasoning performed by the model. This can be @@ -118503,7 +131231,7 @@ Returns an object with `object` set to `response.input_tokens` and an `input_tok - `:high` -- `tool_choice: ToolChoiceOptions | ToolChoiceAllowed | ToolChoiceTypes | 5 more` +- `tool_choice: ToolChoiceOptions | ToolChoiceAllowed | ToolChoiceTypes | 6 more` Controls which tool the model should use, if any. @@ -118643,6 +131371,14 @@ Returns an object with `object` set to `response.input_tokens` and an `input_tok - `:custom` + - `class SpecificProgrammaticToolCallingParam` + + - `type: :programmatic_tool_calling` + + The tool to call. Always `programmatic_tool_calling`. + + - `:programmatic_tool_calling` + - `class ToolChoiceApplyPatch` Forces the model to call the apply_patch tool when executing a tool call. @@ -118697,6 +131433,8 @@ Returns an object with `object` set to `response.input_tokens` and an `input_tok A tool that runs Python code to help generate a response to a prompt. + - `class ProgrammaticToolCalling` + - `class ImageGeneration` A tool that generates images using the GPT image models.