diff --git a/en/resources/responses/methods/compact/index.md b/en/resources/responses/methods/compact/index.md index 2951385..fb6858d 100644 --- a/en/resources/responses/methods/compact/index.md +++ b/en/resources/responses/methods/compact/index.md @@ -2,19 +2,23 @@ **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](/docs/guides/conversation-state#managing-the-context-window). For ZDR-compatible compaction details, see [Compaction (advanced)](/docs/guides/conversation-state#compaction-advanced). +Compact a response ### Body Parameters -- `model: "gpt-5.4" or "gpt-5.4-mini" or "gpt-5.4-nano" or 89 more or string` +- `model: "gpt-5.6-sol" or "gpt-5.6-terra" or "gpt-5.6-luna" or 92 more or 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. + + - `"gpt-5.6-sol" or "gpt-5.6-terra" or "gpt-5.6-luna" or 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. - 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](/docs/models) to browse and compare available models. + - `"gpt-5.6-sol"` - - `"gpt-5.4" or "gpt-5.4-mini" or "gpt-5.4-nano" or 89 more` + - `"gpt-5.6-terra"` - 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](/docs/models) to browse and compare available models. + - `"gpt-5.6-luna"` - `"gpt-5.4"` @@ -202,7 +206,7 @@ Learn when and how to compact long-running conversations in the [conversation st - `string` -- `input: optional string or array of EasyInputMessage or object { content, role, status, type } or ResponseOutputMessage or 27 more` +- `input: optional string or array of EasyInputMessage or object { content, role, status, type } or ResponseOutputMessage or 29 more` Text, image, or file inputs to the model, used to generate a response @@ -210,7 +214,7 @@ Learn when and how to compact long-running conversations in the [conversation st A text input to the model, equivalent to a text input with the `user` role. - - `array of EasyInputMessage or object { content, role, status, type } or ResponseOutputMessage or 27 more` + - `array of EasyInputMessage or object { content, role, status, type } or ResponseOutputMessage or 29 more` A list of one or many input items to the model, containing different content types. @@ -236,7 +240,7 @@ Learn when and how to compact long-running conversations in the [conversation st A list of one or many input items to the model, containing different content types. - - `ResponseInputText object { text, type }` + - `ResponseInputText object { text, type, prompt_cache_breakpoint }` A text input to the model. @@ -250,9 +254,19 @@ Learn when and how to compact long-running conversations in the [conversation st - `"input_text"` - - `ResponseInputImage object { detail, type, file_id, image_url }` + - `prompt_cache_breakpoint: optional object { 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"` - An image input to the model. Learn about [image inputs](/docs/guides/vision). + - `ResponseInputImage object { detail, type, file_id, 2 more }` + + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - `detail: "low" or "high" or "auto" or "original"` @@ -280,7 +294,17 @@ 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. - - `ResponseInputFile object { type, detail, file_data, 3 more }` + - `prompt_cache_breakpoint: optional object { 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"` + + - `ResponseInputFile object { type, detail, file_data, 4 more }` A file input to the model. @@ -290,9 +314,11 @@ Learn when and how to compact long-running conversations in the [conversation st - `"input_file"` - - `detail: optional "low" or "high"` + - `detail: optional "auto" or "low" or "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"` @@ -314,6 +340,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: optional object { 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" or "assistant" or "system" or "developer"` The role of the message input. One of `user`, `assistant`, `system`, or @@ -393,7 +429,7 @@ Learn when and how to compact long-running conversations in the [conversation st The content of the output message. - - `ResponseOutputText object { annotations, logprobs, text, type }` + - `ResponseOutputText object { annotations, text, type, logprobs }` A text output from the model. @@ -497,15 +533,17 @@ Learn when and how to compact long-running conversations in the [conversation st - `"file_path"` - - `logprobs: array of object { token, bytes, logprob, top_logprobs }` + - `text: string` - - `token: string` + The text output from the model. - - `bytes: array of number` + - `type: "output_text"` - - `logprob: number` + The type of the output text. Always `output_text`. - - `top_logprobs: array of object { token, bytes, logprob }` + - `"output_text"` + + - `logprobs: optional array of object { token, bytes, logprob, top_logprobs }` - `token: string` @@ -513,15 +551,13 @@ Learn when and how to compact long-running conversations in the [conversation st - `logprob: number` - - `text: string` - - The text output from the model. + - `top_logprobs: array of object { token, bytes, logprob }` - - `type: "output_text"` + - `token: string` - The type of the output text. Always `output_text`. + - `bytes: array of number` - - `"output_text"` + - `logprob: number` - `ResponseOutputRefusal object { refusal, type }` @@ -573,7 +609,7 @@ Learn when and how to compact long-running conversations in the [conversation st - `FileSearchCall object { id, queries, status, 2 more }` The results of a file search tool call. See the - [file search guide](/docs/guides/tools-file-search) for more information. + [file search guide](https://platform.openai.com/docs/guides/tools-file-search) for more information. - `id: string` @@ -641,7 +677,7 @@ Learn when and how to compact long-running conversations in the [conversation st - `ComputerCall object { id, call_id, pending_safety_checks, 4 more }` A tool call to a computer use tool. See the - [computer use guide](/docs/guides/tools-computer-use) for more information. + [computer use guide](https://platform.openai.com/docs/guides/tools-computer-use) for more information. - `id: string` @@ -684,7 +720,7 @@ Learn when and how to compact long-running conversations in the [conversation st - `"computer_call"` - - `action: optional ComputerAction` + - `action: optional object { button, type, x, 2 more } or object { keys, type, x, y } or object { path, type, keys } or 6 more` A click action. @@ -888,38 +924,193 @@ Learn when and how to compact long-running conversations in the [conversation st A click action. + - `button: "left" or "right" or "wheel" or 2 more` + + Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. + + - `"left"` + + - `"right"` + + - `"wheel"` + + - `"back"` + + - `"forward"` + + - `type: "click"` + + Specifies the event type. For a click action, this property is always `click`. + + - `"click"` + + - `x: number` + + The x-coordinate where the click occurred. + + - `y: number` + + The y-coordinate where the click occurred. + + - `keys: optional array of string` + + The keys being held while clicking. + - `DoubleClick object { keys, type, x, y }` A double click action. + - `keys: array of string` + + The keys being held while double-clicking. + + - `type: "double_click"` + + Specifies the event type. For a double click action, this property is always set to `double_click`. + + - `"double_click"` + + - `x: number` + + The x-coordinate where the double click occurred. + + - `y: number` + + The y-coordinate where the double click occurred. + - `Drag object { path, type, keys }` A drag action. + - `path: array of object { x, y }` + + An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg + + ``` + [ + { x: 100, y: 200 }, + { x: 200, y: 300 } + ] + ``` + + - `x: number` + + The x-coordinate. + + - `y: number` + + The y-coordinate. + + - `type: "drag"` + + Specifies the event type. For a drag action, this property is always set to `drag`. + + - `"drag"` + + - `keys: optional array of string` + + The keys being held while dragging the mouse. + - `Keypress object { keys, type }` A collection of keypresses the model would like to perform. + - `keys: array of string` + + The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. + + - `type: "keypress"` + + Specifies the event type. For a keypress action, this property is always set to `keypress`. + + - `"keypress"` + - `Move object { type, x, y, keys }` A mouse move action. + - `type: "move"` + + Specifies the event type. For a move action, this property is always set to `move`. + + - `"move"` + + - `x: number` + + The x-coordinate to move to. + + - `y: number` + + The y-coordinate to move to. + + - `keys: optional array of string` + + The keys being held while moving the mouse. + - `Screenshot object { type }` A screenshot action. + - `type: "screenshot"` + + Specifies the event type. For a screenshot action, this property is always set to `screenshot`. + + - `"screenshot"` + - `Scroll object { scroll_x, scroll_y, type, 3 more }` A scroll action. + - `scroll_x: number` + + The horizontal scroll distance. + + - `scroll_y: number` + + The vertical scroll distance. + + - `type: "scroll"` + + Specifies the event type. For a scroll action, this property is always set to `scroll`. + + - `"scroll"` + + - `x: number` + + The x-coordinate where the scroll occurred. + + - `y: number` + + The y-coordinate where the scroll occurred. + + - `keys: optional array of string` + + The keys being held while scrolling. + - `Type object { text, type }` An action to type in text. + - `text: string` + + The text to type. + + - `type: "type"` + + Specifies the event type. For a type action, this property is always set to `type`. + + - `"type"` + - `Wait object { type }` A wait action. + - `type: "wait"` + + Specifies the event type. For a wait action, this property is always set to `wait`. + + - `"wait"` + - `ComputerCallOutput object { call_id, output, type, 3 more }` The output of a computer tool call. @@ -986,7 +1177,7 @@ Learn when and how to compact long-running conversations in the [conversation st - `WebSearchCall object { id, action, status, type }` The results of a web search tool call. See the - [web search guide](/docs/guides/tools-web-search) for more information. + [web search guide](https://platform.openai.com/docs/guides/tools-web-search) for more information. - `id: string` @@ -1079,10 +1270,10 @@ Learn when and how to compact long-running conversations in the [conversation st - `"web_search_call"` - - `FunctionCall object { arguments, call_id, name, 4 more }` + - `FunctionCall object { arguments, call_id, name, 5 more }` A tool call to run a function. See the - [function calling guide](/docs/guides/function-calling) for more information. + [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. - `arguments: string` @@ -1106,6 +1297,26 @@ Learn when and how to compact long-running conversations in the [conversation st The unique ID of the function tool call. + - `caller: optional object { type } or object { caller_id, type }` + + The execution context that produced this tool call. + + - `Direct object { type }` + + - `type: "direct"` + + - `"direct"` + + - `Program object { caller_id, type }` + + - `caller_id: string` + + The call ID of the program item that produced this tool call. + + - `type: "program"` + + - `"program"` + - `namespace: optional string` The namespace of the function to run. @@ -1121,7 +1332,7 @@ Learn when and how to compact long-running conversations in the [conversation st - `"incomplete"` - - `FunctionCallOutput object { call_id, output, type, 2 more }` + - `FunctionCallOutput object { call_id, output, type, 3 more }` The output of a function tool call. @@ -1129,7 +1340,7 @@ Learn when and how to compact long-running conversations in the [conversation st The unique ID of the function tool call generated by the model. - - `output: string or array of ResponseInputTextContent or ResponseInputImageContent or ResponseInputFileContent` + - `output: string or ResponseFunctionCallOutputItemList` Text, image, or file output of the function tool call. @@ -1137,11 +1348,11 @@ Learn when and how to compact long-running conversations in the [conversation st A JSON string of the output of the function tool call. - - `array of ResponseInputTextContent or ResponseInputImageContent or ResponseInputFileContent` + - `ResponseFunctionCallOutputItemList = array of ResponseFunctionCallOutputItem` An array of content outputs (text, image, file) for the function tool call. - - `ResponseInputTextContent object { text, type }` + - `ResponseInputTextContent object { text, type, prompt_cache_breakpoint }` A text input to the model. @@ -1155,9 +1366,19 @@ Learn when and how to compact long-running conversations in the [conversation st - `"input_text"` - - `ResponseInputImageContent object { type, detail, file_id, image_url }` + - `prompt_cache_breakpoint: optional object { 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"` - An image input to the model. Learn about [image inputs](/docs/guides/vision) + The breakpoint mode. Always `explicit`. + + - `"explicit"` + + - `ResponseInputImageContent object { type, detail, file_id, 2 more }` + + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) - `type: "input_image"` @@ -1185,7 +1406,17 @@ 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. - - `ResponseInputFileContent object { type, detail, file_data, 3 more }` + - `prompt_cache_breakpoint: optional object { 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"` + + - `ResponseInputFileContent object { type, detail, file_data, 4 more }` A file input to the model. @@ -1195,9 +1426,11 @@ Learn when and how to compact long-running conversations in the [conversation st - `"input_file"` - - `detail: optional "low" or "high"` + - `detail: optional "auto" or "low" or "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"` @@ -1219,6 +1452,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: optional object { 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`. @@ -1229,6 +1472,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: optional object { type } or object { caller_id, type }` + + The execution context that produced this tool call. + + - `Direct object { type }` + + - `type: "direct"` + + The caller type. Always `direct`. + + - `"direct"` + + - `Program object { caller_id, type }` + + - `caller_id: string` + + The call ID of the program item that produced this tool call. + + - `type: "program"` + + The caller type. Always `program`. + + - `"program"` + - `status: optional "in_progress" or "completed" or "incomplete"` The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. @@ -1279,11 +1546,11 @@ Learn when and how to compact long-running conversations in the [conversation st - `ToolSearchOutput object { tools, type, id, 3 more }` - - `tools: array of object { name, parameters, strict, 3 more } or object { type, vector_store_ids, filters, 2 more } or object { type } or 12 more` + - `tools: array of object { name, parameters, strict, 5 more } or object { type, vector_store_ids, filters, 2 more } or object { type } or 13 more` The loaded tool definitions returned by the tool search output. - - `Function object { name, parameters, strict, 3 more }` + - `Function object { name, parameters, strict, 5 more }` 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). @@ -1297,7 +1564,7 @@ Learn when and how to compact long-running conversations in the [conversation st - `strict: boolean` - Whether to enforce strict parameter validation. Default `true`. + Whether strict parameter validation is enforced for this function tool. - `type: "function"` @@ -1305,6 +1572,14 @@ Learn when and how to compact long-running conversations in the [conversation st - `"function"` + - `allowed_callers: optional array of "direct" or "programmatic"` + + The tool invocation context(s). + + - `"direct"` + + - `"programmatic"` + - `defer_loading: optional boolean` Whether this function is deferred and loaded via tool search. @@ -1313,6 +1588,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: optional map[unknown]` + + A JSON schema object describing the JSON value encoded in string outputs for this function. + - `FileSearch object { type, vector_store_ids, filters, 2 more }` 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). @@ -1483,7 +1762,7 @@ Learn when and how to compact long-running conversations in the [conversation st - `WebSearch object { type, filters, search_context_size, user_location }` Search the Internet for sources related to the prompt. Learn more about the - [web search tool](/docs/guides/tools-web-search). + [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - `type: "web_search" or "web_search_2025_08_26"` @@ -1540,10 +1819,10 @@ Learn when and how to compact long-running conversations in the [conversation st - `"approximate"` - - `Mcp object { server_label, type, allowed_tools, 8 more }` + - `Mcp object { server_label, type, allowed_callers, 9 more }` Give the model access to additional tools via remote Model Context Protocol - (MCP) servers. [Learn more about MCP](/docs/guides/tools-remote-mcp). + (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). - `server_label: string` @@ -1555,6 +1834,14 @@ Learn when and how to compact long-running conversations in the [conversation st - `"mcp"` + - `allowed_callers: optional array of "direct" or "programmatic"` + + The tool invocation context(s). + + - `"direct"` + + - `"programmatic"` + - `allowed_tools: optional array of string or object { read_only, tool_names }` List of allowed tool names or a filter object. @@ -1587,7 +1874,7 @@ Learn when and how to compact long-running conversations in the [conversation st Identifier for service connectors, like those available in ChatGPT. One of `server_url`, `connector_id`, or `tunnel_id` must be provided. Learn more - about service connectors [here](/docs/guides/tools-remote-mcp#connectors). + about service connectors [here](https://platform.openai.com/docs/guides/tools-remote-mcp#connectors). Currently supported `connector_id` values are: @@ -1687,7 +1974,7 @@ Learn when and how to compact long-running conversations in the [conversation st The Secure MCP Tunnel ID to use instead of a direct server URL. One of `server_url`, `connector_id`, or `tunnel_id` must be provided. - - `CodeInterpreter object { container, type }` + - `CodeInterpreter object { container, type, allowed_callers }` A tool that runs Python code to help generate a response to a prompt. @@ -1773,6 +2060,22 @@ Learn when and how to compact long-running conversations in the [conversation st - `"code_interpreter"` + - `allowed_callers: optional array of "direct" or "programmatic"` + + The tool invocation context(s). + + - `"direct"` + + - `"programmatic"` + + - `ProgrammaticToolCalling object { type }` + + - `type: "programmatic_tool_calling"` + + The type of the tool. Always `programmatic_tool_calling`. + + - `"programmatic_tool_calling"` + - `ImageGeneration object { type, action, background, 9 more }` A tool that generates images using the GPT image models. @@ -1795,8 +2098,19 @@ Learn when and how to compact long-running conversations in the [conversation st - `background: optional "transparent" or "opaque" or "auto"` - Background type for the generated image. One of `transparent`, - `opaque`, or `auto`. Default: `auto`. + Allows to set transparency for the background of the generated image(s). + This parameter is only supported for GPT image models that support + transparent backgrounds. Must be one of `transparent`, `opaque`, or + `auto` (default value). When `auto` is used, the model will + automatically determine the best background for the image. + + `gpt-image-2` and `gpt-image-2-2026-04-21` do not support + transparent backgrounds. Requests with `background` set to + `transparent` will return an error for these models; use `opaque` or + `auto` instead. + + If `transparent`, the output format needs to support transparency, + so it should be set to either `png` (default value) or `webp`. - `"transparent"` @@ -1825,13 +2139,13 @@ Learn when and how to compact long-running conversations in the [conversation st Base64-encoded mask image. - - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` + - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-2" or 3 more` The image generation model to use. Default: `gpt-image-1`. - `string` - - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` + - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-2" or 3 more` The image generation model to use. Default: `gpt-image-1`. @@ -1839,7 +2153,13 @@ Learn when and how to compact long-running conversations in the [conversation st - `"gpt-image-1-mini"` - - `"gpt-image-1.5"` + - `"gpt-image-2"` + + - `"gpt-image-2-2026-04-21"` + + - `"gpt-image-1.5"` + + - `"chatgpt-image-latest"` - `moderation: optional "auto" or "low"` @@ -1909,7 +2229,7 @@ Learn when and how to compact long-running conversations in the [conversation st - `"local_shell"` - - `Shell object { type, environment }` + - `Shell object { type, allowed_callers, environment }` A tool that allows the model to execute shell commands. @@ -1919,6 +2239,14 @@ Learn when and how to compact long-running conversations in the [conversation st - `"shell"` + - `allowed_callers: optional array of "direct" or "programmatic"` + + The tool invocation context(s). + + - `"direct"` + + - `"programmatic"` + - `environment: optional ContainerAuto or LocalEnvironment or ContainerReference` - `ContainerAuto object { type, file_ids, memory_limit, 2 more }` @@ -2045,9 +2373,9 @@ Learn when and how to compact long-running conversations in the [conversation st - `"container_reference"` - - `Custom object { name, type, defer_loading, 2 more }` + - `Custom object { name, type, allowed_callers, 3 more }` - A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) + 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) - `name: string` @@ -2059,6 +2387,14 @@ Learn when and how to compact long-running conversations in the [conversation st - `"custom"` + - `allowed_callers: optional array of "direct" or "programmatic"` + + The tool invocation context(s). + + - `"direct"` + + - `"programmatic"` + - `defer_loading: optional boolean` Whether this tool should be deferred and discovered via tool search. @@ -2115,11 +2451,11 @@ 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 of object { name, type, defer_loading, 3 more } or object { name, type, defer_loading, 2 more }` + - `tools: array of object { name, type, allowed_callers, 5 more } or object { name, type, allowed_callers, 3 more }` The function/custom tools available inside this namespace. - - `Function object { name, type, defer_loading, 3 more }` + - `Function object { name, type, allowed_callers, 5 more }` - `name: string` @@ -2127,19 +2463,33 @@ Learn when and how to compact long-running conversations in the [conversation st - `"function"` + - `allowed_callers: optional array of "direct" or "programmatic"` + + The tool invocation context(s). + + - `"direct"` + + - `"programmatic"` + - `defer_loading: optional boolean` Whether this function should be deferred and discovered via tool search. - `description: optional string` + - `output_schema: optional map[unknown]` + + A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. + - `parameters: optional unknown` - `strict: optional boolean` - - `Custom object { name, type, defer_loading, 2 more }` + 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. - A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) + - `Custom object { name, type, allowed_callers, 3 more }` + + 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) - `name: string` @@ -2151,6 +2501,14 @@ Learn when and how to compact long-running conversations in the [conversation st - `"custom"` + - `allowed_callers: optional array of "direct" or "programmatic"` + + The tool invocation context(s). + + - `"direct"` + + - `"programmatic"` + - `defer_loading: optional boolean` Whether this tool should be deferred and discovered via tool search. @@ -2249,7 +2607,7 @@ Learn when and how to compact long-running conversations in the [conversation st The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - - `ApplyPatch object { type }` + - `ApplyPatch object { type, allowed_callers }` Allows the assistant to create, delete, or update files using unified diffs. @@ -2259,6 +2617,14 @@ Learn when and how to compact long-running conversations in the [conversation st - `"apply_patch"` + - `allowed_callers: optional array of "direct" or "programmatic"` + + The tool invocation context(s). + + - `"direct"` + + - `"programmatic"` + - `type: "tool_search_output"` The item type. Always `tool_search_output`. @@ -2299,11 +2665,11 @@ Learn when and how to compact long-running conversations in the [conversation st - `"developer"` - - `tools: array of object { name, parameters, strict, 3 more } or object { type, vector_store_ids, filters, 2 more } or object { type } or 12 more` + - `tools: array of object { name, parameters, strict, 5 more } or object { type, vector_store_ids, filters, 2 more } or object { type } or 13 more` A list of additional tools made available at this item. - - `Function object { name, parameters, strict, 3 more }` + - `Function object { name, parameters, strict, 5 more }` 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). @@ -2317,7 +2683,7 @@ Learn when and how to compact long-running conversations in the [conversation st - `strict: boolean` - Whether to enforce strict parameter validation. Default `true`. + Whether strict parameter validation is enforced for this function tool. - `type: "function"` @@ -2325,6 +2691,14 @@ Learn when and how to compact long-running conversations in the [conversation st - `"function"` + - `allowed_callers: optional array of "direct" or "programmatic"` + + The tool invocation context(s). + + - `"direct"` + + - `"programmatic"` + - `defer_loading: optional boolean` Whether this function is deferred and loaded via tool search. @@ -2333,6 +2707,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: optional map[unknown]` + + A JSON schema object describing the JSON value encoded in string outputs for this function. + - `FileSearch object { type, vector_store_ids, filters, 2 more }` 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). @@ -2436,7 +2814,7 @@ Learn when and how to compact long-running conversations in the [conversation st - `WebSearch object { type, filters, search_context_size, user_location }` Search the Internet for sources related to the prompt. Learn more about the - [web search tool](/docs/guides/tools-web-search). + [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - `type: "web_search" or "web_search_2025_08_26"` @@ -2493,10 +2871,10 @@ Learn when and how to compact long-running conversations in the [conversation st - `"approximate"` - - `Mcp object { server_label, type, allowed_tools, 8 more }` + - `Mcp object { server_label, type, allowed_callers, 9 more }` Give the model access to additional tools via remote Model Context Protocol - (MCP) servers. [Learn more about MCP](/docs/guides/tools-remote-mcp). + (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). - `server_label: string` @@ -2508,6 +2886,14 @@ Learn when and how to compact long-running conversations in the [conversation st - `"mcp"` + - `allowed_callers: optional array of "direct" or "programmatic"` + + The tool invocation context(s). + + - `"direct"` + + - `"programmatic"` + - `allowed_tools: optional array of string or object { read_only, tool_names }` List of allowed tool names or a filter object. @@ -2540,7 +2926,7 @@ Learn when and how to compact long-running conversations in the [conversation st Identifier for service connectors, like those available in ChatGPT. One of `server_url`, `connector_id`, or `tunnel_id` must be provided. Learn more - about service connectors [here](/docs/guides/tools-remote-mcp#connectors). + about service connectors [here](https://platform.openai.com/docs/guides/tools-remote-mcp#connectors). Currently supported `connector_id` values are: @@ -2640,7 +3026,7 @@ Learn when and how to compact long-running conversations in the [conversation st The Secure MCP Tunnel ID to use instead of a direct server URL. One of `server_url`, `connector_id`, or `tunnel_id` must be provided. - - `CodeInterpreter object { container, type }` + - `CodeInterpreter object { container, type, allowed_callers }` A tool that runs Python code to help generate a response to a prompt. @@ -2694,6 +3080,22 @@ Learn when and how to compact long-running conversations in the [conversation st - `"code_interpreter"` + - `allowed_callers: optional array of "direct" or "programmatic"` + + The tool invocation context(s). + + - `"direct"` + + - `"programmatic"` + + - `ProgrammaticToolCalling object { type }` + + - `type: "programmatic_tool_calling"` + + The type of the tool. Always `programmatic_tool_calling`. + + - `"programmatic_tool_calling"` + - `ImageGeneration object { type, action, background, 9 more }` A tool that generates images using the GPT image models. @@ -2716,8 +3118,19 @@ Learn when and how to compact long-running conversations in the [conversation st - `background: optional "transparent" or "opaque" or "auto"` - Background type for the generated image. One of `transparent`, - `opaque`, or `auto`. Default: `auto`. + Allows to set transparency for the background of the generated image(s). + This parameter is only supported for GPT image models that support + transparent backgrounds. Must be one of `transparent`, `opaque`, or + `auto` (default value). When `auto` is used, the model will + automatically determine the best background for the image. + + `gpt-image-2` and `gpt-image-2-2026-04-21` do not support + transparent backgrounds. Requests with `background` set to + `transparent` will return an error for these models; use `opaque` or + `auto` instead. + + If `transparent`, the output format needs to support transparency, + so it should be set to either `png` (default value) or `webp`. - `"transparent"` @@ -2746,13 +3159,13 @@ Learn when and how to compact long-running conversations in the [conversation st Base64-encoded mask image. - - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` + - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-2" or 3 more` The image generation model to use. Default: `gpt-image-1`. - `string` - - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` + - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-2" or 3 more` The image generation model to use. Default: `gpt-image-1`. @@ -2760,8 +3173,14 @@ Learn when and how to compact long-running conversations in the [conversation st - `"gpt-image-1-mini"` + - `"gpt-image-2"` + + - `"gpt-image-2-2026-04-21"` + - `"gpt-image-1.5"` + - `"chatgpt-image-latest"` + - `moderation: optional "auto" or "low"` Moderation level for the generated image. Default: `auto`. @@ -2830,7 +3249,7 @@ Learn when and how to compact long-running conversations in the [conversation st - `"local_shell"` - - `Shell object { type, environment }` + - `Shell object { type, allowed_callers, environment }` A tool that allows the model to execute shell commands. @@ -2840,6 +3259,14 @@ Learn when and how to compact long-running conversations in the [conversation st - `"shell"` + - `allowed_callers: optional array of "direct" or "programmatic"` + + The tool invocation context(s). + + - `"direct"` + + - `"programmatic"` + - `environment: optional ContainerAuto or LocalEnvironment or ContainerReference` - `ContainerAuto object { type, file_ids, memory_limit, 2 more }` @@ -2848,9 +3275,9 @@ Learn when and how to compact long-running conversations in the [conversation st - `ContainerReference object { container_id, type }` - - `Custom object { name, type, defer_loading, 2 more }` + - `Custom object { name, type, allowed_callers, 3 more }` - A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) + 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) - `name: string` @@ -2862,6 +3289,14 @@ Learn when and how to compact long-running conversations in the [conversation st - `"custom"` + - `allowed_callers: optional array of "direct" or "programmatic"` + + The tool invocation context(s). + + - `"direct"` + + - `"programmatic"` + - `defer_loading: optional boolean` Whether this tool should be deferred and discovered via tool search. @@ -2886,11 +3321,11 @@ 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 of object { name, type, defer_loading, 3 more } or object { name, type, defer_loading, 2 more }` + - `tools: array of object { name, type, allowed_callers, 5 more } or object { name, type, allowed_callers, 3 more }` The function/custom tools available inside this namespace. - - `Function object { name, type, defer_loading, 3 more }` + - `Function object { name, type, allowed_callers, 5 more }` - `name: string` @@ -2898,19 +3333,33 @@ Learn when and how to compact long-running conversations in the [conversation st - `"function"` + - `allowed_callers: optional array of "direct" or "programmatic"` + + The tool invocation context(s). + + - `"direct"` + + - `"programmatic"` + - `defer_loading: optional boolean` Whether this function should be deferred and discovered via tool search. - `description: optional string` + - `output_schema: optional map[unknown]` + + A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. + - `parameters: optional unknown` - `strict: optional boolean` - - `Custom object { name, type, defer_loading, 2 more }` + 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. - A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) + - `Custom object { name, type, allowed_callers, 3 more }` + + 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) - `name: string` @@ -2922,6 +3371,14 @@ Learn when and how to compact long-running conversations in the [conversation st - `"custom"` + - `allowed_callers: optional array of "direct" or "programmatic"` + + The tool invocation context(s). + + - `"direct"` + + - `"programmatic"` + - `defer_loading: optional boolean` Whether this tool should be deferred and discovered via tool search. @@ -3020,7 +3477,7 @@ Learn when and how to compact long-running conversations in the [conversation st The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - - `ApplyPatch object { type }` + - `ApplyPatch object { type, allowed_callers }` Allows the assistant to create, delete, or update files using unified diffs. @@ -3030,6 +3487,14 @@ Learn when and how to compact long-running conversations in the [conversation st - `"apply_patch"` + - `allowed_callers: optional array of "direct" or "programmatic"` + + The tool invocation context(s). + + - `"direct"` + + - `"programmatic"` + - `type: "additional_tools"` The item type. Always `additional_tools`. @@ -3045,13 +3510,13 @@ Learn when and how to compact long-running conversations in the [conversation st A description of the chain of thought used by a reasoning model while generating a response. Be sure to include these items in your `input` to the Responses API for subsequent turns of a conversation if you are manually - [managing context](/docs/guides/conversation-state). + [managing context](https://platform.openai.com/docs/guides/conversation-state). - `id: string` The unique identifier of the reasoning content. - - `summary: array of SummaryTextContent` + - `summary: array of object { text, type }` Reasoning summary content. @@ -3103,7 +3568,7 @@ Learn when and how to compact long-running conversations in the [conversation st - `Compaction object { encrypted_content, type, id }` - A compaction item generated by the [`v1/responses/compact` API](/docs/api-reference/responses/compact). + A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). - `encrypted_content: string` @@ -3304,7 +3769,7 @@ Learn when and how to compact long-running conversations in the [conversation st - `"incomplete"` - - `ShellCall object { action, call_id, type, 3 more }` + - `ShellCall object { action, call_id, type, 4 more }` A tool representing a request to execute one or more shell commands. @@ -3338,6 +3803,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: optional object { type } or object { caller_id, type }` + + The execution context that produced this tool call. + + - `Direct object { type }` + + - `type: "direct"` + + The caller type. Always `direct`. + + - `"direct"` + + - `Program object { caller_id, type }` + + - `caller_id: string` + + The call ID of the program item that produced this tool call. + + - `type: "program"` + + The caller type. Always `program`. + + - `"program"` + - `environment: optional LocalEnvironment or ContainerReference` The environment to execute the shell commands in. @@ -3356,7 +3845,7 @@ Learn when and how to compact long-running conversations in the [conversation st - `"incomplete"` - - `ShellCallOutput object { call_id, output, type, 3 more }` + - `ShellCallOutput object { call_id, output, type, 4 more }` The streamed output items emitted by a shell tool call. @@ -3414,6 +3903,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: optional object { type } or object { caller_id, type }` + + The execution context that produced this tool call. + + - `Direct object { type }` + + - `type: "direct"` + + The caller type. Always `direct`. + + - `"direct"` + + - `Program object { caller_id, type }` + + - `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: optional number` The maximum number of UTF-8 characters captured for this shell call's combined output. @@ -3428,7 +3941,7 @@ Learn when and how to compact long-running conversations in the [conversation st - `"incomplete"` - - `ApplyPatchCall object { call_id, operation, status, 2 more }` + - `ApplyPatchCall object { call_id, operation, status, 3 more }` A tool call representing a request to create, delete, or update files using diff patches. @@ -3508,7 +4021,31 @@ 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. - - `ApplyPatchCallOutput object { call_id, status, type, 2 more }` + - `caller: optional object { type } or object { caller_id, type }` + + The execution context that produced this tool call. + + - `Direct object { type }` + + - `type: "direct"` + + The caller type. Always `direct`. + + - `"direct"` + + - `Program object { caller_id, type }` + + - `caller_id: string` + + The call ID of the program item that produced this tool call. + + - `type: "program"` + + The caller type. Always `program`. + + - `"program"` + + - `ApplyPatchCallOutput object { call_id, status, type, 3 more }` The streamed output emitted by an apply patch tool call. @@ -3534,6 +4071,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: optional object { type } or object { caller_id, type }` + + The execution context that produced this tool call. + + - `Direct object { type }` + + - `type: "direct"` + + The caller type. Always `direct`. + + - `"direct"` + + - `Program object { caller_id, type }` + + - `caller_id: string` + + The call ID of the program item that produced this tool call. + + - `type: "program"` + + The caller type. Always `program`. + + - `"program"` + - `output: optional string` Optional human-readable log text from the apply patch tool (e.g., patch results or errors). @@ -3685,7 +4246,7 @@ Learn when and how to compact long-running conversations in the [conversation st - `"failed"` - - `CustomToolCallOutput object { call_id, output, type, id }` + - `CustomToolCallOutput object { call_id, output, type, 2 more }` The output of a custom tool call from your code, being sent back to the model. @@ -3706,15 +4267,15 @@ Learn when and how to compact long-running conversations in the [conversation st Text, image, or file output of the custom tool call. - - `ResponseInputText object { text, type }` + - `ResponseInputText object { text, type, prompt_cache_breakpoint }` A text input to the model. - - `ResponseInputImage object { detail, type, file_id, image_url }` + - `ResponseInputImage object { detail, type, file_id, 2 more }` - An image input to the model. Learn about [image inputs](/docs/guides/vision). + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - `ResponseInputFile object { type, detail, file_data, 3 more }` + - `ResponseInputFile object { type, detail, file_data, 4 more }` A file input to the model. @@ -3728,7 +4289,31 @@ 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. - - `CustomToolCall object { call_id, input, name, 3 more }` + - `caller: optional object { type } or object { caller_id, type }` + + The execution context that produced this tool call. + + - `Direct object { type }` + + - `type: "direct"` + + The caller type. Always `direct`. + + - `"direct"` + + - `Program object { caller_id, type }` + + - `caller_id: string` + + The call ID of the program item that produced this tool call. + + - `type: "program"` + + The caller type. Always `program`. + + - `"program"` + + - `CustomToolCall object { call_id, input, name, 4 more }` A call to a custom tool created by the model. @@ -3754,6 +4339,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: optional object { type } or object { caller_id, type }` + + The execution context that produced this tool call. + + - `Direct object { type }` + + - `type: "direct"` + + - `"direct"` + + - `Program object { caller_id, type }` + + - `caller_id: string` + + The call ID of the program item that produced this tool call. + + - `type: "program"` + + - `"program"` + - `namespace: optional string` The namespace of the custom tool being called. @@ -3782,6 +4387,58 @@ Learn when and how to compact long-running conversations in the [conversation st - `"item_reference"` + - `Program object { id, call_id, code, 2 more }` + + - `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"` + + - `ProgramOutput object { id, call_id, result, 2 more }` + + - `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" or "incomplete"` + + The terminal status of the program output. + + - `"completed"` + + - `"incomplete"` + + - `type: "program_output"` + + The item type. Always `program_output`. + + - `"program_output"` + - `instructions: optional string` A system (or developer) message inserted into the model's context. @@ -3789,12 +4446,30 @@ Learn when and how to compact long-running conversations in the [conversation st - `previous_response_id: optional string` - The unique ID of the previous response to the model. Use this to create multi-turn conversations. Learn more about [conversation state](/docs/guides/conversation-state). Cannot be used in conjunction with `conversation`. + The unique ID of the previous response to the model. Use this to create multi-turn conversations. Learn more about [conversation state](https://platform.openai.com/docs/guides/conversation-state). Cannot be used in conjunction with `conversation`. - `prompt_cache_key: optional string` A key to use when reading from or writing to the prompt cache. +- `prompt_cache_options: optional object { 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: optional "implicit" or "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: optional "30m"` + + The minimum lifetime applied to every implicit and explicit cache breakpoint written by the request. Defaults to `30m`, which is currently the only supported value. The backend may retain cache entries for longer. + + - `"30m"` + - `prompt_cache_retention: optional "in_memory" or "24h"` How long to retain a prompt cache entry created by this request. @@ -3833,37 +4508,23 @@ Learn when and how to compact long-running conversations in the [conversation st - `"response.compaction"` - - `output: array of Message or object { arguments, call_id, name, 4 more } or object { id, arguments, call_id, 4 more } or 23 more` + - `output: array of ResponseOutputItem` - The compacted list of output items. + The compacted list of output items. This is a list of all user messages, followed by a single compaction item. - - `Message object { id, content, role, 3 more }` + - `ResponseOutputMessage object { id, content, role, 3 more }` - A message to or from the model. + An output message from the model. - `id: string` - The unique ID of the message. - - - `content: array of ResponseInputText or ResponseOutputText or TextContent or 6 more` - - The content of the message - - - `ResponseInputText object { text, type }` - - A text input to the model. - - - `text: string` - - The text input to the model. - - - `type: "input_text"` + The unique ID of the output message. - The type of the input item. Always `input_text`. + - `content: array of ResponseOutputText or ResponseOutputRefusal` - - `"input_text"` + The content of the output message. - - `ResponseOutputText object { annotations, logprobs, text, type }` + - `ResponseOutputText object { annotations, text, type, logprobs }` A text output from the model. @@ -3967,7 +4628,17 @@ Learn when and how to compact long-running conversations in the [conversation st - `"file_path"` - - `logprobs: array of object { token, bytes, logprob, top_logprobs }` + - `text: string` + + The text output from the model. + + - `type: "output_text"` + + The type of the output text. Always `output_text`. + + - `"output_text"` + + - `logprobs: optional array of object { token, bytes, logprob, top_logprobs }` - `token: string` @@ -3983,311 +4654,320 @@ Learn when and how to compact long-running conversations in the [conversation st - `logprob: number` - - `text: string` + - `ResponseOutputRefusal object { refusal, type }` - The text output from the model. + A refusal from the model. - - `type: "output_text"` + - `refusal: string` - The type of the output text. Always `output_text`. + The refusal explanation from the model. - - `"output_text"` + - `type: "refusal"` - - `TextContent object { text, type }` + The type of the refusal. Always `refusal`. - A text content. + - `"refusal"` - - `text: string` + - `role: "assistant"` - - `type: "text"` + The role of the output message. Always `assistant`. - - `"text"` + - `"assistant"` - - `SummaryTextContent object { text, type }` + - `status: "in_progress" or "completed" or "incomplete"` - A summary text from the model. + The status of the message input. One of `in_progress`, `completed`, or + `incomplete`. Populated when input items are returned via API. - - `text: string` + - `"in_progress"` - A summary of the reasoning output from the model so far. + - `"completed"` - - `type: "summary_text"` + - `"incomplete"` - The type of the object. Always `summary_text`. + - `type: "message"` - - `"summary_text"` + The type of the output message. Always `message`. - - `ReasoningText object { text, type }` + - `"message"` - Reasoning text from the model. + - `phase: optional "commentary" or "final_answer"` - - `text: string` + Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). + For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend + phase on all assistant messages — dropping it can degrade performance. Not used for user messages. - The reasoning text from the model. + - `"commentary"` - - `type: "reasoning_text"` + - `"final_answer"` - The type of the reasoning text. Always `reasoning_text`. - - - `"reasoning_text"` + - `FileSearchCall object { id, queries, status, 2 more }` - - `ResponseOutputRefusal object { refusal, type }` + The results of a file search tool call. See the + [file search guide](https://platform.openai.com/docs/guides/tools-file-search) for more information. - A refusal from the model. + - `id: string` - - `refusal: string` + The unique ID of the file search tool call. - The refusal explanation from the model. + - `queries: array of string` - - `type: "refusal"` + The queries used to search for files. - The type of the refusal. Always `refusal`. + - `status: "in_progress" or "searching" or "completed" or 2 more` - - `"refusal"` + The status of the file search tool call. One of `in_progress`, + `searching`, `incomplete` or `failed`, - - `ResponseInputImage object { detail, type, file_id, image_url }` + - `"in_progress"` - An image input to the model. Learn about [image inputs](/docs/guides/vision). + - `"searching"` - - `detail: "low" or "high" or "auto" or "original"` + - `"completed"` - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + - `"incomplete"` - - `"low"` + - `"failed"` - - `"high"` + - `type: "file_search_call"` - - `"auto"` + The type of the file search tool call. Always `file_search_call`. - - `"original"` + - `"file_search_call"` - - `type: "input_image"` + - `results: optional array of object { attributes, file_id, filename, 2 more }` - The type of the input item. Always `input_image`. + The results of the file search tool call. - - `"input_image"` + - `attributes: optional map[string or number or boolean]` - - `file_id: optional string` + Set of 16 key-value pairs that can be attached to an object. This can be + useful for storing additional information about the object in a structured + format, and querying for objects via API or the dashboard. Keys are strings + with a maximum length of 64 characters. Values are strings with a maximum + length of 512 characters, booleans, or numbers. - The ID of the file to be sent to the model. + - `string` - - `image_url: optional string` + - `number` - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + - `boolean` - - `ComputerScreenshotContent object { detail, file_id, image_url, type }` + - `file_id: optional string` - A screenshot of a computer. + The unique ID of the file. - - `detail: "low" or "high" or "auto" or "original"` + - `filename: optional string` - The detail level of the screenshot image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + The name of the file. - - `"low"` + - `score: optional number` - - `"high"` + The relevance score of the file - a value between 0 and 1. - - `"auto"` + - `text: optional string` - - `"original"` + The text that was retrieved from the file. - - `file_id: string` + - `FunctionCall object { arguments, call_id, name, 5 more }` - The identifier of an uploaded file that contains the screenshot. + A tool call to run a function. See the + [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. - - `image_url: string` + - `arguments: string` - The URL of the screenshot image. + A JSON string of the arguments to pass to the function. - - `type: "computer_screenshot"` + - `call_id: string` - Specifies the event type. For a computer screenshot, this property is always set to `computer_screenshot`. + The unique ID of the function tool call generated by the model. - - `"computer_screenshot"` + - `name: string` - - `ResponseInputFile object { type, detail, file_data, 3 more }` + The name of the function to run. - A file input to the model. + - `type: "function_call"` - - `type: "input_file"` + The type of the function tool call. Always `function_call`. - The type of the input item. Always `input_file`. + - `"function_call"` - - `"input_file"` + - `id: optional string` - - `detail: optional "low" or "high"` + The unique ID of the function tool call. - 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`. + - `caller: optional object { type } or object { caller_id, type }` - - `"low"` + The execution context that produced this tool call. - - `"high"` + - `Direct object { type }` - - `file_data: optional string` + - `type: "direct"` - The content of the file to be sent to the model. + - `"direct"` - - `file_id: optional string` + - `Program object { caller_id, type }` - The ID of the file to be sent to the model. + - `caller_id: string` - - `file_url: optional string` + The call ID of the program item that produced this tool call. - The URL of the file to be sent to the model. + - `type: "program"` - - `filename: optional string` + - `"program"` - The name of the file to be sent to the model. + - `namespace: optional string` - - `role: "unknown" or "user" or "assistant" or 5 more` + The namespace of the function to run. - The role of the message. One of `unknown`, `user`, `assistant`, `system`, `critic`, `discriminator`, `developer`, or `tool`. + - `status: optional "in_progress" or "completed" or "incomplete"` - - `"unknown"` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `"user"` + - `"in_progress"` - - `"assistant"` + - `"completed"` - - `"system"` + - `"incomplete"` - - `"critic"` + - `FunctionCallOutput object { id, call_id, output, 4 more }` - - `"discriminator"` + - `id: string` - - `"developer"` + The unique ID of the function call tool output. - - `"tool"` + - `call_id: string` - - `status: "in_progress" or "completed" or "incomplete"` + The unique ID of the function tool call generated by the model. - The status of item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. + - `output: string or array of ResponseInputText or ResponseInputImage or ResponseInputFile` - - `"in_progress"` + The output from the function call generated by your code. + Can be a string or an list of output content. - - `"completed"` + - `StringOutput = string` - - `"incomplete"` + A string of the output of the function call. - - `type: "message"` + - `OutputContentList = array of ResponseInputText or ResponseInputImage or ResponseInputFile` - The type of the message. Always set to `message`. + Text, image, or file output of the function call. - - `"message"` + - `ResponseInputText object { text, type, prompt_cache_breakpoint }` - - `phase: optional "commentary" or "final_answer"` + A text input to the model. - Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend phase on all assistant messages — dropping it can degrade performance. Not used for user messages. + - `text: string` - - `"commentary"` + The text input to the model. - - `"final_answer"` + - `type: "input_text"` - - `FunctionCall object { arguments, call_id, name, 4 more }` + The type of the input item. Always `input_text`. - A tool call to run a function. See the - [function calling guide](/docs/guides/function-calling) for more information. + - `"input_text"` - - `arguments: string` + - `prompt_cache_breakpoint: optional object { mode }` - A JSON string of the arguments to pass to the function. + 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. - - `call_id: string` + - `mode: "explicit"` - The unique ID of the function tool call generated by the model. + The breakpoint mode. Always `explicit`. - - `name: string` + - `"explicit"` - The name of the function to run. + - `ResponseInputImage object { detail, type, file_id, 2 more }` - - `type: "function_call"` + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - The type of the function tool call. Always `function_call`. + - `detail: "low" or "high" or "auto" or "original"` - - `"function_call"` + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - - `id: optional string` + - `"low"` - The unique ID of the function tool call. + - `"high"` - - `namespace: optional string` + - `"auto"` - The namespace of the function to run. + - `"original"` - - `status: optional "in_progress" or "completed" or "incomplete"` + - `type: "input_image"` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + The type of the input item. Always `input_image`. - - `"in_progress"` + - `"input_image"` - - `"completed"` + - `file_id: optional string` - - `"incomplete"` + The ID of the file to be sent to the model. - - `ToolSearchCall object { id, arguments, call_id, 4 more }` + - `image_url: optional string` - - `id: string` + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - The unique ID of the tool search call item. + - `prompt_cache_breakpoint: optional object { mode }` - - `arguments: unknown` + 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. - Arguments used for the tool search call. + - `mode: "explicit"` - - `call_id: string` + The breakpoint mode. Always `explicit`. - The unique ID of the tool search call generated by the model. + - `"explicit"` - - `execution: "server" or "client"` + - `ResponseInputFile object { type, detail, file_data, 4 more }` - Whether tool search was executed by the server or by the client. + A file input to the model. - - `"server"` + - `type: "input_file"` - - `"client"` + The type of the input item. Always `input_file`. - - `status: "in_progress" or "completed" or "incomplete"` + - `"input_file"` - The status of the tool search call item that was recorded. + - `detail: optional "auto" or "low" or "high"` - - `"in_progress"` + 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`. - - `"completed"` + - `"auto"` - - `"incomplete"` + - `"low"` - - `type: "tool_search_call"` + - `"high"` - The type of the item. Always `tool_search_call`. + - `file_data: optional string` - - `"tool_search_call"` + The content of the file to be sent to the model. - - `created_by: optional string` + - `file_id: optional string` - The identifier of the actor that created the item. + The ID of the file to be sent to the model. - - `ToolSearchOutput object { id, call_id, execution, 4 more }` + - `file_url: optional string` - - `id: string` + The URL of the file to be sent to the model. - The unique ID of the tool search output item. + - `filename: optional string` - - `call_id: string` + The name of the file to be sent to the model. - The unique ID of the tool search call generated by the model. + - `prompt_cache_breakpoint: optional object { mode }` - - `execution: "server" or "client"` + 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. - Whether tool search was executed by the server or by the client. + - `mode: "explicit"` - - `"server"` + The breakpoint mode. Always `explicit`. - - `"client"` + - `"explicit"` - `status: "in_progress" or "completed" or "incomplete"` - The status of the tool search output item that was recorded. + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - `"in_progress"` @@ -4295,1516 +4975,1853 @@ Learn when and how to compact long-running conversations in the [conversation st - `"incomplete"` - - `tools: array of object { name, parameters, strict, 3 more } or object { type, vector_store_ids, filters, 2 more } or object { type } or 12 more` + - `type: "function_call_output"` - The loaded tool definitions returned by tool search. + The type of the function tool call output. Always `function_call_output`. - - `Function object { name, parameters, strict, 3 more }` + - `"function_call_output"` - 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). + - `caller: optional object { type } or object { caller_id, type }` - - `name: string` + The execution context that produced this tool call. - The name of the function to call. + - `Direct object { type }` - - `parameters: map[unknown]` + - `type: "direct"` - A JSON schema object describing the parameters of the function. + The caller type. Always `direct`. - - `strict: boolean` + - `"direct"` - Whether to enforce strict parameter validation. Default `true`. + - `Program object { caller_id, type }` - - `type: "function"` + - `caller_id: string` - The type of the function tool. Always `function`. + The call ID of the program item that produced this tool call. - - `"function"` + - `type: "program"` - - `defer_loading: optional boolean` + The caller type. Always `program`. - Whether this function is deferred and loaded via tool search. + - `"program"` - - `description: optional string` + - `created_by: optional string` - A description of the function. Used by the model to determine whether or not to call the function. + The identifier of the actor that created the item. - - `FileSearch object { type, vector_store_ids, filters, 2 more }` + - `WebSearchCall object { id, action, status, type }` - 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). + The results of a web search tool call. See the + [web search guide](https://platform.openai.com/docs/guides/tools-web-search) for more information. - - `type: "file_search"` + - `id: string` - The type of the file search tool. Always `file_search`. + The unique ID of the web search tool call. - - `"file_search"` + - `action: object { type, queries, query, sources } or object { type, url } or object { pattern, type, url }` - - `vector_store_ids: array of string` + An object describing the specific action taken in this web search call. + Includes details on how the model used the web (search, open_page, find_in_page). - The IDs of the vector stores to search. + - `Search object { type, queries, query, sources }` - - `filters: optional ComparisonFilter or CompoundFilter` + Action type "search" - Performs a web search query. - A filter to apply. + - `type: "search"` - - `ComparisonFilter object { key, type, value }` + The action type. - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + - `"search"` - - `key: string` + - `queries: optional array of string` - The key to compare against the value. + The search queries. - - `type: "eq" or "ne" or "gt" or 5 more` + - `query: optional string` - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + The search query. - - `eq`: equals - - `ne`: not equal - - `gt`: greater than - - `gte`: greater than or equal - - `lt`: less than - - `lte`: less than or equal - - `in`: in - - `nin`: not in + - `sources: optional array of object { type, url }` - - `"eq"` + The sources used in the search. - - `"ne"` + - `type: "url"` - - `"gt"` + The type of source. Always `url`. - - `"gte"` + - `"url"` - - `"lt"` + - `url: string` - - `"lte"` + The URL of the source. - - `"in"` + - `OpenPage object { type, url }` - - `"nin"` + Action type "open_page" - Opens a specific URL from search results. - - `value: string or number or boolean or array of string or number` + - `type: "open_page"` - The value to compare against the attribute key; supports string, number, or boolean types. + The action type. - - `string` + - `"open_page"` - - `number` + - `url: optional string` - - `boolean` + The URL opened by the model. - - `array of string or number` + - `FindInPage object { pattern, type, url }` - - `string` + Action type "find_in_page": Searches for a pattern within a loaded page. - - `number` + - `pattern: string` - - `CompoundFilter object { filters, type }` + The pattern or text to search for within the page. - Combine multiple filters using `and` or `or`. + - `type: "find_in_page"` - - `filters: array of ComparisonFilter or unknown` + The action type. - Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. + - `"find_in_page"` - - `ComparisonFilter object { key, type, value }` + - `url: string` - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + The URL of the page searched for the pattern. - - `unknown` + - `status: "in_progress" or "searching" or "completed" or "failed"` - - `type: "and" or "or"` + The status of the web search tool call. - Type of operation: `and` or `or`. + - `"in_progress"` - - `"and"` + - `"searching"` - - `"or"` + - `"completed"` - - `max_num_results: optional number` + - `"failed"` - The maximum number of results to return. This number should be between 1 and 50 inclusive. + - `type: "web_search_call"` - - `ranking_options: optional object { hybrid_search, ranker, score_threshold }` + The type of the web search tool call. Always `web_search_call`. - Ranking options for search. + - `"web_search_call"` - - `hybrid_search: optional object { embedding_weight, text_weight }` + - `ComputerCall object { id, call_id, pending_safety_checks, 4 more }` - Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. + A tool call to a computer use tool. See the + [computer use guide](https://platform.openai.com/docs/guides/tools-computer-use) for more information. - - `embedding_weight: number` + - `id: string` - The weight of the embedding in the reciprocal ranking fusion. + The unique ID of the computer call. - - `text_weight: number` + - `call_id: string` - The weight of the text in the reciprocal ranking fusion. + An identifier used when responding to the tool call with output. - - `ranker: optional "auto" or "default-2024-11-15"` + - `pending_safety_checks: array of object { id, code, message }` - The ranker to use for the file search. + The pending safety checks for the computer call. - - `"auto"` + - `id: string` - - `"default-2024-11-15"` + The ID of the pending safety check. - - `score_threshold: optional number` + - `code: optional string` - The score threshold for the file search, a number between 0 and 1. Numbers closer to 1 will attempt to return only the most relevant results, but may return fewer results. + The type of the pending safety check. - - `Computer object { type }` + - `message: optional string` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + Details about the pending safety check. - - `type: "computer"` + - `status: "in_progress" or "completed" or "incomplete"` - The type of the computer tool. Always `computer`. + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `"computer"` + - `"in_progress"` - - `ComputerUsePreview object { display_height, display_width, environment, type }` + - `"completed"` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `"incomplete"` - - `display_height: number` + - `type: "computer_call"` - The height of the computer display. + The type of the computer call. Always `computer_call`. - - `display_width: number` + - `"computer_call"` - The width of the computer display. + - `action: optional object { button, type, x, 2 more } or object { keys, type, x, y } or object { path, type, keys } or 6 more` - - `environment: "windows" or "mac" or "linux" or 2 more` + A click action. - The type of computer environment to control. + - `Click object { button, type, x, 2 more }` - - `"windows"` + A click action. - - `"mac"` + - `button: "left" or "right" or "wheel" or 2 more` - - `"linux"` + Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. - - `"ubuntu"` + - `"left"` - - `"browser"` + - `"right"` - - `type: "computer_use_preview"` + - `"wheel"` - The type of the computer use tool. Always `computer_use_preview`. + - `"back"` - - `"computer_use_preview"` + - `"forward"` - - `WebSearch object { type, filters, search_context_size, user_location }` + - `type: "click"` - Search the Internet for sources related to the prompt. Learn more about the - [web search tool](/docs/guides/tools-web-search). + Specifies the event type. For a click action, this property is always `click`. - - `type: "web_search" or "web_search_2025_08_26"` + - `"click"` - The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. + - `x: number` - - `"web_search"` + The x-coordinate where the click occurred. + + - `y: number` + + The y-coordinate where the click occurred. + + - `keys: optional array of string` + + The keys being held while clicking. + + - `DoubleClick object { keys, type, x, y }` + + A double click action. + + - `keys: array of string` + + The keys being held while double-clicking. + + - `type: "double_click"` + + Specifies the event type. For a double click action, this property is always set to `double_click`. + + - `"double_click"` + + - `x: number` + + The x-coordinate where the double click occurred. + + - `y: number` + + The y-coordinate where the double click occurred. + + - `Drag object { path, type, keys }` + + A drag action. + + - `path: array of object { x, y }` + + An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg + + ``` + [ + { x: 100, y: 200 }, + { x: 200, y: 300 } + ] + ``` + + - `x: number` + + The x-coordinate. + + - `y: number` + + The y-coordinate. + + - `type: "drag"` + + Specifies the event type. For a drag action, this property is always set to `drag`. + + - `"drag"` + + - `keys: optional array of string` + + The keys being held while dragging the mouse. + + - `Keypress object { keys, type }` + + A collection of keypresses the model would like to perform. + + - `keys: array of string` + + The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. + + - `type: "keypress"` + + Specifies the event type. For a keypress action, this property is always set to `keypress`. + + - `"keypress"` + + - `Move object { type, x, y, keys }` + + A mouse move action. + + - `type: "move"` + + Specifies the event type. For a move action, this property is always set to `move`. + + - `"move"` + + - `x: number` + + The x-coordinate to move to. + + - `y: number` + + The y-coordinate to move to. + + - `keys: optional array of string` + + The keys being held while moving the mouse. + + - `Screenshot object { type }` + + A screenshot action. + + - `type: "screenshot"` + + Specifies the event type. For a screenshot action, this property is always set to `screenshot`. + + - `"screenshot"` + + - `Scroll object { scroll_x, scroll_y, type, 3 more }` + + A scroll action. + + - `scroll_x: number` + + The horizontal scroll distance. + + - `scroll_y: number` + + The vertical scroll distance. + + - `type: "scroll"` + + Specifies the event type. For a scroll action, this property is always set to `scroll`. + + - `"scroll"` + + - `x: number` + + The x-coordinate where the scroll occurred. + + - `y: number` + + The y-coordinate where the scroll occurred. + + - `keys: optional array of string` + + The keys being held while scrolling. + + - `Type object { text, type }` + + An action to type in text. + + - `text: string` + + The text to type. + + - `type: "type"` + + Specifies the event type. For a type action, this property is always set to `type`. + + - `"type"` + + - `Wait object { type }` + + A wait action. + + - `type: "wait"` + + Specifies the event type. For a wait action, this property is always set to `wait`. + + - `"wait"` + + - `actions: optional ComputerActionList` + + Flattened batched actions for `computer_use`. Each action includes an + `type` discriminator and action-specific fields. + + - `Click object { button, type, x, 2 more }` + + A click action. + + - `button: "left" or "right" or "wheel" or 2 more` + + Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. + + - `"left"` + + - `"right"` + + - `"wheel"` + + - `"back"` + + - `"forward"` + + - `type: "click"` + + Specifies the event type. For a click action, this property is always `click`. + + - `"click"` + + - `x: number` + + The x-coordinate where the click occurred. + + - `y: number` + + The y-coordinate where the click occurred. + + - `keys: optional array of string` + + The keys being held while clicking. + + - `DoubleClick object { keys, type, x, y }` + + A double click action. + + - `keys: array of string` + + The keys being held while double-clicking. + + - `type: "double_click"` + + Specifies the event type. For a double click action, this property is always set to `double_click`. + + - `"double_click"` + + - `x: number` + + The x-coordinate where the double click occurred. + + - `y: number` + + The y-coordinate where the double click occurred. + + - `Drag object { path, type, keys }` + + A drag action. + + - `path: array of object { x, y }` + + An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg + + ``` + [ + { x: 100, y: 200 }, + { x: 200, y: 300 } + ] + ``` + + - `x: number` + + The x-coordinate. + + - `y: number` + + The y-coordinate. + + - `type: "drag"` + + Specifies the event type. For a drag action, this property is always set to `drag`. + + - `"drag"` + + - `keys: optional array of string` + + The keys being held while dragging the mouse. + + - `Keypress object { keys, type }` + + A collection of keypresses the model would like to perform. + + - `keys: array of string` + + The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. + + - `type: "keypress"` + + Specifies the event type. For a keypress action, this property is always set to `keypress`. + + - `"keypress"` + + - `Move object { type, x, y, keys }` + + A mouse move action. + + - `type: "move"` + + Specifies the event type. For a move action, this property is always set to `move`. + + - `"move"` + + - `x: number` + + The x-coordinate to move to. + + - `y: number` + + The y-coordinate to move to. + + - `keys: optional array of string` + + The keys being held while moving the mouse. + + - `Screenshot object { type }` + + A screenshot action. + + - `type: "screenshot"` + + Specifies the event type. For a screenshot action, this property is always set to `screenshot`. + + - `"screenshot"` + + - `Scroll object { scroll_x, scroll_y, type, 3 more }` + + A scroll action. + + - `scroll_x: number` + + The horizontal scroll distance. + + - `scroll_y: number` + + The vertical scroll distance. + + - `type: "scroll"` + + Specifies the event type. For a scroll action, this property is always set to `scroll`. + + - `"scroll"` + + - `x: number` + + The x-coordinate where the scroll occurred. + + - `y: number` + + The y-coordinate where the scroll occurred. + + - `keys: optional array of string` + + The keys being held while scrolling. + + - `Type object { text, type }` + + An action to type in text. + + - `text: string` + + The text to type. + + - `type: "type"` + + Specifies the event type. For a type action, this property is always set to `type`. + + - `"type"` + + - `Wait object { type }` + + A wait action. - - `"web_search_2025_08_26"` + - `type: "wait"` - - `filters: optional object { allowed_domains }` + Specifies the event type. For a wait action, this property is always set to `wait`. - Filters for the search. + - `"wait"` - - `allowed_domains: optional array of string` + - `ComputerCallOutput object { id, call_id, output, 4 more }` - Allowed domains for the search. If not provided, all domains are allowed. - Subdomains of the provided domains are allowed as well. + - `id: string` - Example: `["pubmed.ncbi.nlm.nih.gov"]` + The unique ID of the computer call tool output. - - `search_context_size: optional "low" or "medium" or "high"` + - `call_id: string` - High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. + The ID of the computer tool call that produced the output. - - `"low"` + - `output: ResponseComputerToolCallOutputScreenshot` - - `"medium"` + A computer screenshot image used with the computer use tool. - - `"high"` + - `type: "computer_screenshot"` - - `user_location: optional object { city, country, region, 2 more }` + Specifies the event type. For a computer screenshot, this property is + always set to `computer_screenshot`. - The approximate location of the user. + - `"computer_screenshot"` - - `city: optional string` + - `file_id: optional string` - Free text input for the city of the user, e.g. `San Francisco`. + The identifier of an uploaded file that contains the screenshot. - - `country: optional string` + - `image_url: optional string` - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + The URL of the screenshot image. - - `region: optional string` + - `status: "completed" or "incomplete" or "failed" or "in_progress"` - Free text input for the region of the user, e.g. `California`. + The status of the message input. One of `in_progress`, `completed`, or + `incomplete`. Populated when input items are returned via API. - - `timezone: optional string` + - `"completed"` - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + - `"incomplete"` - - `type: optional "approximate"` + - `"failed"` - The type of location approximation. Always `approximate`. + - `"in_progress"` - - `"approximate"` + - `type: "computer_call_output"` - - `Mcp object { server_label, type, allowed_tools, 8 more }` + The type of the computer tool call output. Always `computer_call_output`. - Give the model access to additional tools via remote Model Context Protocol - (MCP) servers. [Learn more about MCP](/docs/guides/tools-remote-mcp). + - `"computer_call_output"` - - `server_label: string` + - `acknowledged_safety_checks: optional array of object { id, code, message }` - A label for this MCP server, used to identify it in tool calls. + The safety checks reported by the API that have been acknowledged by the + developer. - - `type: "mcp"` + - `id: string` - The type of the MCP tool. Always `mcp`. + The ID of the pending safety check. - - `"mcp"` + - `code: optional string` - - `allowed_tools: optional array of string or object { read_only, tool_names }` + The type of the pending safety check. - List of allowed tool names or a filter object. + - `message: optional string` - - `McpAllowedTools = array of string` + Details about the pending safety check. - A string array of allowed tool names + - `created_by: optional string` - - `McpToolFilter object { read_only, tool_names }` + The identifier of the actor that created the item. - A filter object to specify which tools are allowed. + - `Reasoning object { id, summary, type, 3 more }` - - `read_only: optional boolean` + A description of the chain of thought used by a reasoning model while generating + a response. Be sure to include these items in your `input` to the Responses API + for subsequent turns of a conversation if you are manually + [managing context](https://platform.openai.com/docs/guides/conversation-state). - Indicates whether or not a tool modifies data or is read-only. If an - MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), - it will match this filter. + - `id: string` - - `tool_names: optional array of string` + The unique identifier of the reasoning content. - List of allowed tool names. + - `summary: array of object { text, type }` - - `authorization: optional string` + Reasoning summary content. - An OAuth access token that can be used with a remote MCP server, either - with a custom MCP server URL or a service connector. Your application - must handle the OAuth authorization flow and provide the token here. + - `text: string` - - `connector_id: optional "connector_dropbox" or "connector_gmail" or "connector_googlecalendar" or 5 more` + A summary of the reasoning output from the model so far. - Identifier for service connectors, like those available in ChatGPT. One of - `server_url`, `connector_id`, or `tunnel_id` must be provided. Learn more - about service connectors [here](/docs/guides/tools-remote-mcp#connectors). + - `type: "summary_text"` - Currently supported `connector_id` values are: + The type of the object. Always `summary_text`. - - Dropbox: `connector_dropbox` - - Gmail: `connector_gmail` - - Google Calendar: `connector_googlecalendar` - - Google Drive: `connector_googledrive` - - Microsoft Teams: `connector_microsoftteams` - - Outlook Calendar: `connector_outlookcalendar` - - Outlook Email: `connector_outlookemail` - - SharePoint: `connector_sharepoint` + - `"summary_text"` - - `"connector_dropbox"` + - `type: "reasoning"` - - `"connector_gmail"` + The type of the object. Always `reasoning`. - - `"connector_googlecalendar"` + - `"reasoning"` - - `"connector_googledrive"` + - `content: optional array of object { text, type }` - - `"connector_microsoftteams"` + Reasoning text content. - - `"connector_outlookcalendar"` + - `text: string` - - `"connector_outlookemail"` + The reasoning text from the model. - - `"connector_sharepoint"` + - `type: "reasoning_text"` - - `defer_loading: optional boolean` + The type of the reasoning text. Always `reasoning_text`. - Whether this MCP tool is deferred and discovered via tool search. + - `"reasoning_text"` - - `headers: optional map[string]` + - `encrypted_content: optional string` - Optional HTTP headers to send to the MCP server. Use for authentication - or other purposes. + The encrypted content of the reasoning item - populated when a response is + generated with `reasoning.encrypted_content` in the `include` parameter. - - `require_approval: optional object { always, never } or "always" or "never"` + - `status: optional "in_progress" or "completed" or "incomplete"` - Specify which of the MCP server's tools require approval. + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `McpToolApprovalFilter object { always, never }` + - `"in_progress"` - Specify which of the MCP server's tools require approval. Can be - `always`, `never`, or a filter object associated with tools - that require approval. + - `"completed"` - - `always: optional object { read_only, tool_names }` + - `"incomplete"` - A filter object to specify which tools are allowed. + - `Program object { id, call_id, code, 2 more }` - - `read_only: optional boolean` + - `id: string` - Indicates whether or not a tool modifies data or is read-only. If an - MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), - it will match this filter. + The unique ID of the program item. - - `tool_names: optional array of string` + - `call_id: string` - List of allowed tool names. + The stable call ID of the program item. - - `never: optional object { read_only, tool_names }` + - `code: string` - A filter object to specify which tools are allowed. + The JavaScript source executed by programmatic tool calling. - - `read_only: optional boolean` + - `fingerprint: string` - Indicates whether or not a tool modifies data or is read-only. If an - MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), - it will match this filter. + Opaque program replay fingerprint that must be round-tripped. - - `tool_names: optional array of string` + - `type: "program"` - List of allowed tool names. + The type of the item. Always `program`. - - `McpToolApprovalSetting = "always" or "never"` + - `"program"` - Specify a single approval policy for all tools. One of `always` or - `never`. When set to `always`, all tools will require approval. When - set to `never`, all tools will not require approval. + - `ProgramOutput object { id, call_id, result, 2 more }` - - `"always"` + - `id: string` - - `"never"` + The unique ID of the program output item. - - `server_description: optional string` + - `call_id: string` - Optional description of the MCP server, used to provide more context. + The call ID of the program item. - - `server_url: optional string` + - `result: string` - The URL for the MCP server. One of `server_url`, `connector_id`, or - `tunnel_id` must be provided. + The result produced by the program item. - - `tunnel_id: optional string` + - `status: "completed" or "incomplete"` - The Secure MCP Tunnel ID to use instead of a direct server URL. One of - `server_url`, `connector_id`, or `tunnel_id` must be provided. + The terminal status of the program output item. - - `CodeInterpreter object { container, type }` + - `"completed"` - A tool that runs Python code to help generate a response to a prompt. + - `"incomplete"` - - `container: string or object { type, file_ids, memory_limit, network_policy }` + - `type: "program_output"` - The code interpreter container. Can be a container ID or an object that - specifies uploaded file IDs to make available to your code, along with an - optional `memory_limit` setting. + The type of the item. Always `program_output`. - - `string` + - `"program_output"` - The container ID. + - `ToolSearchCall object { id, arguments, call_id, 4 more }` - - `CodeInterpreterToolAuto object { type, file_ids, memory_limit, network_policy }` + - `id: string` - Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. + The unique ID of the tool search call item. - - `type: "auto"` + - `arguments: unknown` - Always `auto`. + Arguments used for the tool search call. - - `"auto"` + - `call_id: string` - - `file_ids: optional array of string` + The unique ID of the tool search call generated by the model. - An optional list of uploaded files to make available to your code. + - `execution: "server" or "client"` - - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` + Whether tool search was executed by the server or by the client. - The memory limit for the code interpreter container. + - `"server"` - - `"1g"` + - `"client"` - - `"4g"` + - `status: "in_progress" or "completed" or "incomplete"` - - `"16g"` + The status of the tool search call item that was recorded. - - `"64g"` + - `"in_progress"` - - `network_policy: optional ContainerNetworkPolicyDisabled or ContainerNetworkPolicyAllowlist` + - `"completed"` - Network access policy for the container. + - `"incomplete"` - - `ContainerNetworkPolicyDisabled object { type }` + - `type: "tool_search_call"` - - `type: "disabled"` + The type of the item. Always `tool_search_call`. - Disable outbound network access. Always `disabled`. + - `"tool_search_call"` - - `"disabled"` + - `created_by: optional string` - - `ContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` + The identifier of the actor that created the item. - - `allowed_domains: array of string` + - `ToolSearchOutput object { id, call_id, execution, 4 more }` - A list of allowed domains when type is `allowlist`. + - `id: string` - - `type: "allowlist"` + The unique ID of the tool search output item. - Allow outbound network access only to specified domains. Always `allowlist`. + - `call_id: string` - - `"allowlist"` + The unique ID of the tool search call generated by the model. - - `domain_secrets: optional array of ContainerNetworkPolicyDomainSecret` + - `execution: "server" or "client"` - Optional domain-scoped secrets for allowlisted domains. + Whether tool search was executed by the server or by the client. - - `domain: string` + - `"server"` - The domain associated with the secret. + - `"client"` - - `name: string` + - `status: "in_progress" or "completed" or "incomplete"` - The name of the secret to inject for the domain. + The status of the tool search output item that was recorded. - - `value: string` + - `"in_progress"` - The secret value to inject for the domain. + - `"completed"` - - `type: "code_interpreter"` + - `"incomplete"` - The type of the code interpreter tool. Always `code_interpreter`. + - `tools: array of object { name, parameters, strict, 5 more } or object { type, vector_store_ids, filters, 2 more } or object { type } or 13 more` - - `"code_interpreter"` + The loaded tool definitions returned by tool search. - - `ImageGeneration object { type, action, background, 9 more }` + - `Function object { name, parameters, strict, 5 more }` - A tool that generates images using the GPT image models. + 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). - - `type: "image_generation"` + - `name: string` - The type of the image generation tool. Always `image_generation`. + The name of the function to call. - - `"image_generation"` + - `parameters: map[unknown]` - - `action: optional "generate" or "edit" or "auto"` + A JSON schema object describing the parameters of the function. - Whether to generate a new image or edit an existing image. Default: `auto`. + - `strict: boolean` - - `"generate"` + Whether strict parameter validation is enforced for this function tool. - - `"edit"` + - `type: "function"` - - `"auto"` + The type of the function tool. Always `function`. - - `background: optional "transparent" or "opaque" or "auto"` + - `"function"` - Background type for the generated image. One of `transparent`, - `opaque`, or `auto`. Default: `auto`. + - `allowed_callers: optional array of "direct" or "programmatic"` - - `"transparent"` + The tool invocation context(s). - - `"opaque"` + - `"direct"` - - `"auto"` + - `"programmatic"` - - `input_fidelity: optional "high" or "low"` + - `defer_loading: optional boolean` - Control how much effort the model will exert to match the style and features, especially facial features, of input images. This parameter is only supported for `gpt-image-1` and `gpt-image-1.5` and later models, unsupported for `gpt-image-1-mini`. Supports `high` and `low`. Defaults to `low`. + Whether this function is deferred and loaded via tool search. - - `"high"` + - `description: optional string` - - `"low"` + A description of the function. Used by the model to determine whether or not to call the function. - - `input_image_mask: optional object { file_id, image_url }` + - `output_schema: optional map[unknown]` - Optional mask for inpainting. Contains `image_url` - (string, optional) and `file_id` (string, optional). + A JSON schema object describing the JSON value encoded in string outputs for this function. - - `file_id: optional string` + - `FileSearch object { type, vector_store_ids, filters, 2 more }` - File ID for the mask image. + 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). - - `image_url: optional string` + - `type: "file_search"` - Base64-encoded mask image. + The type of the file search tool. Always `file_search`. - - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` + - `"file_search"` - The image generation model to use. Default: `gpt-image-1`. + - `vector_store_ids: array of string` - - `string` + The IDs of the vector stores to search. - - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` + - `filters: optional ComparisonFilter or CompoundFilter` - The image generation model to use. Default: `gpt-image-1`. + A filter to apply. - - `"gpt-image-1"` + - `ComparisonFilter object { key, type, value }` - - `"gpt-image-1-mini"` + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - - `"gpt-image-1.5"` + - `key: string` - - `moderation: optional "auto" or "low"` + The key to compare against the value. - Moderation level for the generated image. Default: `auto`. + - `type: "eq" or "ne" or "gt" or 5 more` - - `"auto"` + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - - `"low"` + - `eq`: equals + - `ne`: not equal + - `gt`: greater than + - `gte`: greater than or equal + - `lt`: less than + - `lte`: less than or equal + - `in`: in + - `nin`: not in - - `output_compression: optional number` + - `"eq"` - Compression level for the output image. Default: 100. + - `"ne"` - - `output_format: optional "png" or "webp" or "jpeg"` + - `"gt"` - The output format of the generated image. One of `png`, `webp`, or - `jpeg`. Default: `png`. + - `"gte"` - - `"png"` + - `"lt"` - - `"webp"` + - `"lte"` - - `"jpeg"` + - `"in"` - - `partial_images: optional number` + - `"nin"` - Number of partial images to generate in streaming mode, from 0 (default value) to 3. + - `value: string or number or boolean or array of string or number` - - `quality: optional "low" or "medium" or "high" or "auto"` + The value to compare against the attribute key; supports string, number, or boolean types. - The quality of the generated image. One of `low`, `medium`, `high`, - or `auto`. Default: `auto`. + - `string` - - `"low"` + - `number` - - `"medium"` + - `boolean` - - `"high"` + - `array of string or number` - - `"auto"` + - `string` - - `size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or "auto"` + - `number` - The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. + - `CompoundFilter object { filters, type }` - - `string` + Combine multiple filters using `and` or `or`. - - `"1024x1024" or "1024x1536" or "1536x1024" or "auto"` + - `filters: array of ComparisonFilter or unknown` - The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. + Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. - - `"1024x1024"` + - `ComparisonFilter object { key, type, value }` - - `"1024x1536"` + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - - `"1536x1024"` + - `unknown` - - `"auto"` + - `type: "and" or "or"` - - `LocalShell object { type }` + Type of operation: `and` or `or`. - A tool that allows the model to execute shell commands in a local environment. + - `"and"` - - `type: "local_shell"` + - `"or"` - The type of the local shell tool. Always `local_shell`. + - `max_num_results: optional number` - - `"local_shell"` + The maximum number of results to return. This number should be between 1 and 50 inclusive. - - `Shell object { type, environment }` + - `ranking_options: optional object { hybrid_search, ranker, score_threshold }` - A tool that allows the model to execute shell commands. + Ranking options for search. - - `type: "shell"` + - `hybrid_search: optional object { embedding_weight, text_weight }` - The type of the shell tool. Always `shell`. + Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. - - `"shell"` + - `embedding_weight: number` - - `environment: optional ContainerAuto or LocalEnvironment or ContainerReference` + The weight of the embedding in the reciprocal ranking fusion. - - `ContainerAuto object { type, file_ids, memory_limit, 2 more }` + - `text_weight: number` - - `type: "container_auto"` + The weight of the text in the reciprocal ranking fusion. - Automatically creates a container for this request + - `ranker: optional "auto" or "default-2024-11-15"` - - `"container_auto"` + The ranker to use for the file search. - - `file_ids: optional array of string` + - `"auto"` - An optional list of uploaded files to make available to your code. + - `"default-2024-11-15"` - - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` + - `score_threshold: optional number` - The memory limit for the container. + The score threshold for the file search, a number between 0 and 1. Numbers closer to 1 will attempt to return only the most relevant results, but may return fewer results. - - `"1g"` + - `Computer object { type }` - - `"4g"` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `"16g"` + - `type: "computer"` - - `"64g"` + The type of the computer tool. Always `computer`. - - `network_policy: optional ContainerNetworkPolicyDisabled or ContainerNetworkPolicyAllowlist` + - `"computer"` - Network access policy for the container. + - `ComputerUsePreview object { display_height, display_width, environment, type }` - - `ContainerNetworkPolicyDisabled object { type }` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `ContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` + - `display_height: number` - - `skills: optional array of SkillReference or InlineSkill` + The height of the computer display. - An optional list of skills referenced by id or inline data. + - `display_width: number` - - `SkillReference object { skill_id, type, version }` + The width of the computer display. - - `skill_id: string` + - `environment: "windows" or "mac" or "linux" or 2 more` - The ID of the referenced skill. + The type of computer environment to control. - - `type: "skill_reference"` + - `"windows"` - References a skill created with the /v1/skills endpoint. + - `"mac"` - - `"skill_reference"` + - `"linux"` - - `version: optional string` + - `"ubuntu"` - Optional skill version. Use a positive integer or 'latest'. Omit for default. + - `"browser"` - - `InlineSkill object { description, name, source, type }` + - `type: "computer_use_preview"` - - `description: string` + The type of the computer use tool. Always `computer_use_preview`. - The description of the skill. + - `"computer_use_preview"` - - `name: string` + - `WebSearch object { type, filters, search_context_size, user_location }` - The name of the skill. + 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). - - `source: InlineSkillSource` + - `type: "web_search" or "web_search_2025_08_26"` - Inline skill payload + The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. - - `data: string` + - `"web_search"` - Base64-encoded skill zip bundle. + - `"web_search_2025_08_26"` - - `media_type: "application/zip"` + - `filters: optional object { allowed_domains }` - The media type of the inline skill payload. Must be `application/zip`. + Filters for the search. - - `"application/zip"` + - `allowed_domains: optional array of string` - - `type: "base64"` + Allowed domains for the search. If not provided, all domains are allowed. + Subdomains of the provided domains are allowed as well. - The type of the inline skill source. Must be `base64`. + Example: `["pubmed.ncbi.nlm.nih.gov"]` - - `"base64"` + - `search_context_size: optional "low" or "medium" or "high"` - - `type: "inline"` + High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. - Defines an inline skill for this request. + - `"low"` - - `"inline"` + - `"medium"` - - `LocalEnvironment object { type, skills }` + - `"high"` - - `type: "local"` + - `user_location: optional object { city, country, region, 2 more }` - Use a local computer environment. + The approximate location of the user. - - `"local"` + - `city: optional string` - - `skills: optional array of LocalSkill` + Free text input for the city of the user, e.g. `San Francisco`. - An optional list of skills. + - `country: optional string` - - `description: string` + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - The description of the skill. + - `region: optional string` - - `name: string` + Free text input for the region of the user, e.g. `California`. - The name of the skill. + - `timezone: optional string` - - `path: string` + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - The path to the directory containing the skill. + - `type: optional "approximate"` - - `ContainerReference object { container_id, type }` + The type of location approximation. Always `approximate`. - - `container_id: string` + - `"approximate"` - The ID of the referenced container. + - `Mcp object { server_label, type, allowed_callers, 9 more }` - - `type: "container_reference"` + 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). - References a container created with the /v1/containers endpoint + - `server_label: string` - - `"container_reference"` + A label for this MCP server, used to identify it in tool calls. - - `Custom object { name, type, defer_loading, 2 more }` + - `type: "mcp"` - A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) + The type of the MCP tool. Always `mcp`. - - `name: string` + - `"mcp"` - The name of the custom tool, used to identify it in tool calls. + - `allowed_callers: optional array of "direct" or "programmatic"` - - `type: "custom"` + The tool invocation context(s). - The type of the custom tool. Always `custom`. + - `"direct"` - - `"custom"` + - `"programmatic"` - - `defer_loading: optional boolean` + - `allowed_tools: optional array of string or object { read_only, tool_names }` - Whether this tool should be deferred and discovered via tool search. + List of allowed tool names or a filter object. - - `description: optional string` + - `McpAllowedTools = array of string` - Optional description of the custom tool, used to provide more context. + A string array of allowed tool names - - `format: optional CustomToolInputFormat` + - `McpToolFilter object { read_only, tool_names }` - The input format for the custom tool. Default is unconstrained text. + A filter object to specify which tools are allowed. - - `Text object { type }` + - `read_only: optional boolean` - Unconstrained free-form text. + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. - - `type: "text"` + - `tool_names: optional array of string` - Unconstrained text format. Always `text`. + List of allowed tool names. - - `"text"` + - `authorization: optional string` - - `Grammar object { definition, syntax, type }` + An OAuth access token that can be used with a remote MCP server, either + with a custom MCP server URL or a service connector. Your application + must handle the OAuth authorization flow and provide the token here. - A grammar defined by the user. + - `connector_id: optional "connector_dropbox" or "connector_gmail" or "connector_googlecalendar" or 5 more` - - `definition: string` + Identifier for service connectors, like those available in ChatGPT. One of + `server_url`, `connector_id`, or `tunnel_id` must be provided. Learn more + about service connectors [here](https://platform.openai.com/docs/guides/tools-remote-mcp#connectors). - The grammar definition. + Currently supported `connector_id` values are: - - `syntax: "lark" or "regex"` + - Dropbox: `connector_dropbox` + - Gmail: `connector_gmail` + - Google Calendar: `connector_googlecalendar` + - Google Drive: `connector_googledrive` + - Microsoft Teams: `connector_microsoftteams` + - Outlook Calendar: `connector_outlookcalendar` + - Outlook Email: `connector_outlookemail` + - SharePoint: `connector_sharepoint` - The syntax of the grammar definition. One of `lark` or `regex`. + - `"connector_dropbox"` - - `"lark"` + - `"connector_gmail"` - - `"regex"` + - `"connector_googlecalendar"` - - `type: "grammar"` + - `"connector_googledrive"` - Grammar format. Always `grammar`. + - `"connector_microsoftteams"` - - `"grammar"` + - `"connector_outlookcalendar"` - - `Namespace object { description, name, tools, type }` + - `"connector_outlookemail"` - Groups function/custom tools under a shared namespace. + - `"connector_sharepoint"` - - `description: string` + - `defer_loading: optional boolean` - A description of the namespace shown to the model. + Whether this MCP tool is deferred and discovered via tool search. - - `name: string` + - `headers: optional map[string]` - The namespace name used in tool calls (for example, `crm`). + Optional HTTP headers to send to the MCP server. Use for authentication + or other purposes. - - `tools: array of object { name, type, defer_loading, 3 more } or object { name, type, defer_loading, 2 more }` + - `require_approval: optional object { always, never } or "always" or "never"` - The function/custom tools available inside this namespace. + Specify which of the MCP server's tools require approval. - - `Function object { name, type, defer_loading, 3 more }` + - `McpToolApprovalFilter object { always, never }` - - `name: string` + Specify which of the MCP server's tools require approval. Can be + `always`, `never`, or a filter object associated with tools + that require approval. - - `type: "function"` + - `always: optional object { read_only, tool_names }` - - `"function"` + A filter object to specify which tools are allowed. - - `defer_loading: optional boolean` + - `read_only: optional boolean` - Whether this function should be deferred and discovered via tool search. + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. - - `description: optional string` + - `tool_names: optional array of string` - - `parameters: optional unknown` + List of allowed tool names. - - `strict: optional boolean` + - `never: optional object { read_only, tool_names }` - - `Custom object { name, type, defer_loading, 2 more }` + A filter object to specify which tools are allowed. - A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) + - `read_only: optional boolean` - - `name: string` + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. - The name of the custom tool, used to identify it in tool calls. + - `tool_names: optional array of string` - - `type: "custom"` + List of allowed tool names. - The type of the custom tool. Always `custom`. + - `McpToolApprovalSetting = "always" or "never"` - - `"custom"` + Specify a single approval policy for all tools. One of `always` or + `never`. When set to `always`, all tools will require approval. When + set to `never`, all tools will not require approval. - - `defer_loading: optional boolean` + - `"always"` - Whether this tool should be deferred and discovered via tool search. + - `"never"` - - `description: optional string` + - `server_description: optional string` - Optional description of the custom tool, used to provide more context. + Optional description of the MCP server, used to provide more context. - - `format: optional CustomToolInputFormat` + - `server_url: optional string` - The input format for the custom tool. Default is unconstrained text. + The URL for the MCP server. One of `server_url`, `connector_id`, or + `tunnel_id` must be provided. - - `type: "namespace"` + - `tunnel_id: optional string` - The type of the tool. Always `namespace`. + The Secure MCP Tunnel ID to use instead of a direct server URL. One of + `server_url`, `connector_id`, or `tunnel_id` must be provided. - - `"namespace"` + - `CodeInterpreter object { container, type, allowed_callers }` - - `ToolSearch object { type, description, execution, parameters }` + A tool that runs Python code to help generate a response to a prompt. - Hosted or BYOT tool search configuration for deferred tools. + - `container: string or object { type, file_ids, memory_limit, network_policy }` - - `type: "tool_search"` + The code interpreter container. Can be a container ID or an object that + specifies uploaded file IDs to make available to your code, along with an + optional `memory_limit` setting. - The type of the tool. Always `tool_search`. + - `string` - - `"tool_search"` + The container ID. - - `description: optional string` + - `CodeInterpreterToolAuto object { type, file_ids, memory_limit, network_policy }` - Description shown to the model for a client-executed tool search tool. + Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. - - `execution: optional "server" or "client"` + - `type: "auto"` - Whether tool search is executed by the server or by the client. + Always `auto`. - - `"server"` + - `"auto"` - - `"client"` + - `file_ids: optional array of string` - - `parameters: optional unknown` + An optional list of uploaded files to make available to your code. - Parameter schema for a client-executed tool search tool. + - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` - - `WebSearchPreview object { type, search_content_types, search_context_size, user_location }` + The memory limit for the code interpreter container. - 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). + - `"1g"` - - `type: "web_search_preview" or "web_search_preview_2025_03_11"` + - `"4g"` - The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. + - `"16g"` - - `"web_search_preview"` + - `"64g"` - - `"web_search_preview_2025_03_11"` + - `network_policy: optional ContainerNetworkPolicyDisabled or ContainerNetworkPolicyAllowlist` - - `search_content_types: optional array of "text" or "image"` + Network access policy for the container. - - `"text"` + - `ContainerNetworkPolicyDisabled object { type }` - - `"image"` + - `type: "disabled"` - - `search_context_size: optional "low" or "medium" or "high"` + Disable outbound network access. Always `disabled`. - High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. + - `"disabled"` - - `"low"` + - `ContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` - - `"medium"` + - `allowed_domains: array of string` - - `"high"` + A list of allowed domains when type is `allowlist`. - - `user_location: optional object { type, city, country, 2 more }` + - `type: "allowlist"` - The user's location. + Allow outbound network access only to specified domains. Always `allowlist`. - - `type: "approximate"` + - `"allowlist"` - The type of location approximation. Always `approximate`. + - `domain_secrets: optional array of ContainerNetworkPolicyDomainSecret` - - `"approximate"` + Optional domain-scoped secrets for allowlisted domains. - - `city: optional string` + - `domain: string` - Free text input for the city of the user, e.g. `San Francisco`. + The domain associated with the secret. - - `country: optional string` + - `name: string` - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + The name of the secret to inject for the domain. - - `region: optional string` + - `value: string` - Free text input for the region of the user, e.g. `California`. + The secret value to inject for the domain. - - `timezone: optional string` + - `type: "code_interpreter"` - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + The type of the code interpreter tool. Always `code_interpreter`. - - `ApplyPatch object { type }` + - `"code_interpreter"` - Allows the assistant to create, delete, or update files using unified diffs. + - `allowed_callers: optional array of "direct" or "programmatic"` - - `type: "apply_patch"` + The tool invocation context(s). - The type of the tool. Always `apply_patch`. + - `"direct"` - - `"apply_patch"` + - `"programmatic"` - - `type: "tool_search_output"` + - `ProgrammaticToolCalling object { type }` - The type of the item. Always `tool_search_output`. + - `type: "programmatic_tool_calling"` - - `"tool_search_output"` + The type of the tool. Always `programmatic_tool_calling`. - - `created_by: optional string` + - `"programmatic_tool_calling"` - The identifier of the actor that created the item. + - `ImageGeneration object { type, action, background, 9 more }` - - `AdditionalTools object { id, role, tools, type }` + A tool that generates images using the GPT image models. - - `id: string` + - `type: "image_generation"` - The unique ID of the additional tools item. + The type of the image generation tool. Always `image_generation`. - - `role: "unknown" or "user" or "assistant" or 5 more` + - `"image_generation"` - The role that provided the additional tools. + - `action: optional "generate" or "edit" or "auto"` - - `"unknown"` + Whether to generate a new image or edit an existing image. Default: `auto`. - - `"user"` + - `"generate"` - - `"assistant"` + - `"edit"` - - `"system"` + - `"auto"` - - `"critic"` + - `background: optional "transparent" or "opaque" or "auto"` - - `"discriminator"` + Allows to set transparency for the background of the generated image(s). + This parameter is only supported for GPT image models that support + transparent backgrounds. Must be one of `transparent`, `opaque`, or + `auto` (default value). When `auto` is used, the model will + automatically determine the best background for the image. - - `"developer"` + `gpt-image-2` and `gpt-image-2-2026-04-21` do not support + transparent backgrounds. Requests with `background` set to + `transparent` will return an error for these models; use `opaque` or + `auto` instead. - - `"tool"` + If `transparent`, the output format needs to support transparency, + so it should be set to either `png` (default value) or `webp`. - - `tools: array of object { name, parameters, strict, 3 more } or object { type, vector_store_ids, filters, 2 more } or object { type } or 12 more` + - `"transparent"` - The additional tool definitions made available at this item. + - `"opaque"` - - `Function object { name, parameters, strict, 3 more }` + - `"auto"` - 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). + - `input_fidelity: optional "high" or "low"` - - `name: string` + Control how much effort the model will exert to match the style and features, especially facial features, of input images. This parameter is only supported for `gpt-image-1` and `gpt-image-1.5` and later models, unsupported for `gpt-image-1-mini`. Supports `high` and `low`. Defaults to `low`. - The name of the function to call. + - `"high"` - - `parameters: map[unknown]` + - `"low"` - A JSON schema object describing the parameters of the function. + - `input_image_mask: optional object { file_id, image_url }` - - `strict: boolean` + Optional mask for inpainting. Contains `image_url` + (string, optional) and `file_id` (string, optional). - Whether to enforce strict parameter validation. Default `true`. + - `file_id: optional string` - - `type: "function"` + File ID for the mask image. - The type of the function tool. Always `function`. + - `image_url: optional string` - - `"function"` + Base64-encoded mask image. - - `defer_loading: optional boolean` + - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-2" or 3 more` - Whether this function is deferred and loaded via tool search. + The image generation model to use. Default: `gpt-image-1`. - - `description: optional string` + - `string` - A description of the function. Used by the model to determine whether or not to call the function. + - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-2" or 3 more` - - `FileSearch object { type, vector_store_ids, filters, 2 more }` + The image generation model to use. Default: `gpt-image-1`. - 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). + - `"gpt-image-1"` - - `type: "file_search"` + - `"gpt-image-1-mini"` - The type of the file search tool. Always `file_search`. + - `"gpt-image-2"` - - `"file_search"` + - `"gpt-image-2-2026-04-21"` - - `vector_store_ids: array of string` + - `"gpt-image-1.5"` - The IDs of the vector stores to search. + - `"chatgpt-image-latest"` - - `filters: optional ComparisonFilter or CompoundFilter` + - `moderation: optional "auto" or "low"` - A filter to apply. + Moderation level for the generated image. Default: `auto`. - - `ComparisonFilter object { key, type, value }` + - `"auto"` - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + - `"low"` - - `CompoundFilter object { filters, type }` + - `output_compression: optional number` - Combine multiple filters using `and` or `or`. + Compression level for the output image. Default: 100. - - `max_num_results: optional number` + - `output_format: optional "png" or "webp" or "jpeg"` - The maximum number of results to return. This number should be between 1 and 50 inclusive. + The output format of the generated image. One of `png`, `webp`, or + `jpeg`. Default: `png`. - - `ranking_options: optional object { hybrid_search, ranker, score_threshold }` + - `"png"` - Ranking options for search. + - `"webp"` - - `hybrid_search: optional object { embedding_weight, text_weight }` + - `"jpeg"` - Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. + - `partial_images: optional number` - - `embedding_weight: number` + Number of partial images to generate in streaming mode, from 0 (default value) to 3. - The weight of the embedding in the reciprocal ranking fusion. + - `quality: optional "low" or "medium" or "high" or "auto"` - - `text_weight: number` + The quality of the generated image. One of `low`, `medium`, `high`, + or `auto`. Default: `auto`. - The weight of the text in the reciprocal ranking fusion. + - `"low"` - - `ranker: optional "auto" or "default-2024-11-15"` + - `"medium"` - The ranker to use for the file search. + - `"high"` - `"auto"` - - `"default-2024-11-15"` - - - `score_threshold: optional number` + - `size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or "auto"` - The score threshold for the file search, a number between 0 and 1. Numbers closer to 1 will attempt to return only the most relevant results, but may return fewer results. + The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. - - `Computer object { type }` + - `string` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `"1024x1024" or "1024x1536" or "1536x1024" or "auto"` - - `type: "computer"` + The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. - The type of the computer tool. Always `computer`. + - `"1024x1024"` - - `"computer"` + - `"1024x1536"` - - `ComputerUsePreview object { display_height, display_width, environment, type }` + - `"1536x1024"` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `"auto"` - - `display_height: number` + - `LocalShell object { type }` - The height of the computer display. + A tool that allows the model to execute shell commands in a local environment. - - `display_width: number` + - `type: "local_shell"` - The width of the computer display. + The type of the local shell tool. Always `local_shell`. - - `environment: "windows" or "mac" or "linux" or 2 more` + - `"local_shell"` - The type of computer environment to control. + - `Shell object { type, allowed_callers, environment }` - - `"windows"` + A tool that allows the model to execute shell commands. - - `"mac"` + - `type: "shell"` - - `"linux"` + The type of the shell tool. Always `shell`. - - `"ubuntu"` + - `"shell"` - - `"browser"` + - `allowed_callers: optional array of "direct" or "programmatic"` - - `type: "computer_use_preview"` + The tool invocation context(s). - The type of the computer use tool. Always `computer_use_preview`. + - `"direct"` - - `"computer_use_preview"` + - `"programmatic"` - - `WebSearch object { type, filters, search_context_size, user_location }` + - `environment: optional ContainerAuto or LocalEnvironment or ContainerReference` - Search the Internet for sources related to the prompt. Learn more about the - [web search tool](/docs/guides/tools-web-search). + - `ContainerAuto object { type, file_ids, memory_limit, 2 more }` - - `type: "web_search" or "web_search_2025_08_26"` + - `type: "container_auto"` - The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. + Automatically creates a container for this request - - `"web_search"` + - `"container_auto"` - - `"web_search_2025_08_26"` + - `file_ids: optional array of string` - - `filters: optional object { allowed_domains }` + An optional list of uploaded files to make available to your code. - Filters for the search. + - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` - - `allowed_domains: optional array of string` + The memory limit for the container. - Allowed domains for the search. If not provided, all domains are allowed. - Subdomains of the provided domains are allowed as well. + - `"1g"` - Example: `["pubmed.ncbi.nlm.nih.gov"]` + - `"4g"` - - `search_context_size: optional "low" or "medium" or "high"` + - `"16g"` - High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. + - `"64g"` - - `"low"` + - `network_policy: optional ContainerNetworkPolicyDisabled or ContainerNetworkPolicyAllowlist` - - `"medium"` + Network access policy for the container. - - `"high"` + - `ContainerNetworkPolicyDisabled object { type }` - - `user_location: optional object { city, country, region, 2 more }` + - `ContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` - The approximate location of the user. + - `skills: optional array of SkillReference or InlineSkill` - - `city: optional string` + An optional list of skills referenced by id or inline data. - Free text input for the city of the user, e.g. `San Francisco`. + - `SkillReference object { skill_id, type, version }` - - `country: optional string` + - `skill_id: string` - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + The ID of the referenced skill. - - `region: optional string` + - `type: "skill_reference"` - Free text input for the region of the user, e.g. `California`. + References a skill created with the /v1/skills endpoint. - - `timezone: optional string` + - `"skill_reference"` - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + - `version: optional string` - - `type: optional "approximate"` + Optional skill version. Use a positive integer or 'latest'. Omit for default. - The type of location approximation. Always `approximate`. + - `InlineSkill object { description, name, source, type }` - - `"approximate"` + - `description: string` - - `Mcp object { server_label, type, allowed_tools, 8 more }` + The description of the skill. - Give the model access to additional tools via remote Model Context Protocol - (MCP) servers. [Learn more about MCP](/docs/guides/tools-remote-mcp). + - `name: string` - - `server_label: string` + The name of the skill. - A label for this MCP server, used to identify it in tool calls. + - `source: InlineSkillSource` - - `type: "mcp"` + Inline skill payload - The type of the MCP tool. Always `mcp`. + - `data: string` - - `"mcp"` + Base64-encoded skill zip bundle. - - `allowed_tools: optional array of string or object { read_only, tool_names }` + - `media_type: "application/zip"` - List of allowed tool names or a filter object. + The media type of the inline skill payload. Must be `application/zip`. - - `McpAllowedTools = array of string` + - `"application/zip"` - A string array of allowed tool names + - `type: "base64"` - - `McpToolFilter object { read_only, tool_names }` + The type of the inline skill source. Must be `base64`. - A filter object to specify which tools are allowed. + - `"base64"` - - `read_only: optional boolean` + - `type: "inline"` - Indicates whether or not a tool modifies data or is read-only. If an - MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), - it will match this filter. + Defines an inline skill for this request. - - `tool_names: optional array of string` + - `"inline"` - List of allowed tool names. + - `LocalEnvironment object { type, skills }` - - `authorization: optional string` + - `type: "local"` - An OAuth access token that can be used with a remote MCP server, either - with a custom MCP server URL or a service connector. Your application - must handle the OAuth authorization flow and provide the token here. + Use a local computer environment. - - `connector_id: optional "connector_dropbox" or "connector_gmail" or "connector_googlecalendar" or 5 more` + - `"local"` - Identifier for service connectors, like those available in ChatGPT. One of - `server_url`, `connector_id`, or `tunnel_id` must be provided. Learn more - about service connectors [here](/docs/guides/tools-remote-mcp#connectors). + - `skills: optional array of LocalSkill` - Currently supported `connector_id` values are: + An optional list of skills. - - Dropbox: `connector_dropbox` - - Gmail: `connector_gmail` - - Google Calendar: `connector_googlecalendar` - - Google Drive: `connector_googledrive` - - Microsoft Teams: `connector_microsoftteams` - - Outlook Calendar: `connector_outlookcalendar` - - Outlook Email: `connector_outlookemail` - - SharePoint: `connector_sharepoint` + - `description: string` - - `"connector_dropbox"` + The description of the skill. - - `"connector_gmail"` + - `name: string` - - `"connector_googlecalendar"` + The name of the skill. - - `"connector_googledrive"` + - `path: string` - - `"connector_microsoftteams"` + The path to the directory containing the skill. - - `"connector_outlookcalendar"` + - `ContainerReference object { container_id, type }` - - `"connector_outlookemail"` + - `container_id: string` - - `"connector_sharepoint"` + The ID of the referenced container. - - `defer_loading: optional boolean` + - `type: "container_reference"` - Whether this MCP tool is deferred and discovered via tool search. + References a container created with the /v1/containers endpoint - - `headers: optional map[string]` + - `"container_reference"` - Optional HTTP headers to send to the MCP server. Use for authentication - or other purposes. + - `Custom object { name, type, allowed_callers, 3 more }` - - `require_approval: optional object { always, never } or "always" or "never"` + 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) - Specify which of the MCP server's tools require approval. + - `name: string` - - `McpToolApprovalFilter object { always, never }` + The name of the custom tool, used to identify it in tool calls. - Specify which of the MCP server's tools require approval. Can be - `always`, `never`, or a filter object associated with tools - that require approval. + - `type: "custom"` - - `always: optional object { read_only, tool_names }` + The type of the custom tool. Always `custom`. - A filter object to specify which tools are allowed. + - `"custom"` - - `read_only: optional boolean` + - `allowed_callers: optional array of "direct" or "programmatic"` - Indicates whether or not a tool modifies data or is read-only. If an - MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), - it will match this filter. + The tool invocation context(s). - - `tool_names: optional array of string` + - `"direct"` - List of allowed tool names. + - `"programmatic"` - - `never: optional object { read_only, tool_names }` + - `defer_loading: optional boolean` - A filter object to specify which tools are allowed. + Whether this tool should be deferred and discovered via tool search. - - `read_only: optional boolean` + - `description: optional string` - Indicates whether or not a tool modifies data or is read-only. If an - MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), - it will match this filter. + Optional description of the custom tool, used to provide more context. - - `tool_names: optional array of string` + - `format: optional CustomToolInputFormat` - List of allowed tool names. + The input format for the custom tool. Default is unconstrained text. - - `McpToolApprovalSetting = "always" or "never"` + - `Text object { type }` - Specify a single approval policy for all tools. One of `always` or - `never`. When set to `always`, all tools will require approval. When - set to `never`, all tools will not require approval. + Unconstrained free-form text. - - `"always"` + - `type: "text"` - - `"never"` + Unconstrained text format. Always `text`. - - `server_description: optional string` + - `"text"` - Optional description of the MCP server, used to provide more context. + - `Grammar object { definition, syntax, type }` - - `server_url: optional string` + A grammar defined by the user. - The URL for the MCP server. One of `server_url`, `connector_id`, or - `tunnel_id` must be provided. + - `definition: string` - - `tunnel_id: optional string` + The grammar definition. - The Secure MCP Tunnel ID to use instead of a direct server URL. One of - `server_url`, `connector_id`, or `tunnel_id` must be provided. + - `syntax: "lark" or "regex"` - - `CodeInterpreter object { container, type }` + The syntax of the grammar definition. One of `lark` or `regex`. - A tool that runs Python code to help generate a response to a prompt. + - `"lark"` - - `container: string or object { type, file_ids, memory_limit, network_policy }` + - `"regex"` - The code interpreter container. Can be a container ID or an object that - specifies uploaded file IDs to make available to your code, along with an - optional `memory_limit` setting. + - `type: "grammar"` - - `string` + Grammar format. Always `grammar`. - The container ID. + - `"grammar"` - - `CodeInterpreterToolAuto object { type, file_ids, memory_limit, network_policy }` + - `Namespace object { description, name, tools, type }` - Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. + Groups function/custom tools under a shared namespace. - - `type: "auto"` + - `description: string` - Always `auto`. + A description of the namespace shown to the model. - - `"auto"` + - `name: string` - - `file_ids: optional array of string` + The namespace name used in tool calls (for example, `crm`). - An optional list of uploaded files to make available to your code. + - `tools: array of object { name, type, allowed_callers, 5 more } or object { name, type, allowed_callers, 3 more }` - - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` + The function/custom tools available inside this namespace. - The memory limit for the code interpreter container. + - `Function object { name, type, allowed_callers, 5 more }` - - `"1g"` + - `name: string` - - `"4g"` + - `type: "function"` - - `"16g"` + - `"function"` - - `"64g"` + - `allowed_callers: optional array of "direct" or "programmatic"` - - `network_policy: optional ContainerNetworkPolicyDisabled or ContainerNetworkPolicyAllowlist` + The tool invocation context(s). - Network access policy for the container. + - `"direct"` - - `ContainerNetworkPolicyDisabled object { type }` + - `"programmatic"` - - `ContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` + - `defer_loading: optional boolean` - - `type: "code_interpreter"` + Whether this function should be deferred and discovered via tool search. - The type of the code interpreter tool. Always `code_interpreter`. + - `description: optional string` - - `"code_interpreter"` + - `output_schema: optional map[unknown]` - - `ImageGeneration object { type, action, background, 9 more }` + A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. - A tool that generates images using the GPT image models. + - `parameters: optional unknown` - - `type: "image_generation"` + - `strict: optional boolean` - The type of the image generation tool. Always `image_generation`. + 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. - - `"image_generation"` + - `Custom object { name, type, allowed_callers, 3 more }` - - `action: optional "generate" or "edit" or "auto"` + 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) - Whether to generate a new image or edit an existing image. Default: `auto`. + - `name: string` - - `"generate"` + The name of the custom tool, used to identify it in tool calls. - - `"edit"` + - `type: "custom"` - - `"auto"` + The type of the custom tool. Always `custom`. - - `background: optional "transparent" or "opaque" or "auto"` + - `"custom"` - Background type for the generated image. One of `transparent`, - `opaque`, or `auto`. Default: `auto`. + - `allowed_callers: optional array of "direct" or "programmatic"` - - `"transparent"` + The tool invocation context(s). - - `"opaque"` + - `"direct"` - - `"auto"` + - `"programmatic"` - - `input_fidelity: optional "high" or "low"` + - `defer_loading: optional boolean` - Control how much effort the model will exert to match the style and features, especially facial features, of input images. This parameter is only supported for `gpt-image-1` and `gpt-image-1.5` and later models, unsupported for `gpt-image-1-mini`. Supports `high` and `low`. Defaults to `low`. + Whether this tool should be deferred and discovered via tool search. - - `"high"` + - `description: optional string` - - `"low"` + Optional description of the custom tool, used to provide more context. - - `input_image_mask: optional object { file_id, image_url }` + - `format: optional CustomToolInputFormat` - Optional mask for inpainting. Contains `image_url` - (string, optional) and `file_id` (string, optional). + The input format for the custom tool. Default is unconstrained text. - - `file_id: optional string` + - `type: "namespace"` - File ID for the mask image. + The type of the tool. Always `namespace`. - - `image_url: optional string` + - `"namespace"` - Base64-encoded mask image. + - `ToolSearch object { type, description, execution, parameters }` - - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` + Hosted or BYOT tool search configuration for deferred tools. - The image generation model to use. Default: `gpt-image-1`. + - `type: "tool_search"` - - `string` + The type of the tool. Always `tool_search`. - - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` + - `"tool_search"` - The image generation model to use. Default: `gpt-image-1`. + - `description: optional string` - - `"gpt-image-1"` + Description shown to the model for a client-executed tool search tool. - - `"gpt-image-1-mini"` + - `execution: optional "server" or "client"` - - `"gpt-image-1.5"` + Whether tool search is executed by the server or by the client. - - `moderation: optional "auto" or "low"` + - `"server"` - Moderation level for the generated image. Default: `auto`. + - `"client"` - - `"auto"` + - `parameters: optional unknown` - - `"low"` + Parameter schema for a client-executed tool search tool. - - `output_compression: optional number` + - `WebSearchPreview object { type, search_content_types, search_context_size, user_location }` - Compression level for the output image. Default: 100. + 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). - - `output_format: optional "png" or "webp" or "jpeg"` + - `type: "web_search_preview" or "web_search_preview_2025_03_11"` - The output format of the generated image. One of `png`, `webp`, or - `jpeg`. Default: `png`. + The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. - - `"png"` + - `"web_search_preview"` - - `"webp"` + - `"web_search_preview_2025_03_11"` - - `"jpeg"` + - `search_content_types: optional array of "text" or "image"` - - `partial_images: optional number` + - `"text"` - Number of partial images to generate in streaming mode, from 0 (default value) to 3. + - `"image"` - - `quality: optional "low" or "medium" or "high" or "auto"` + - `search_context_size: optional "low" or "medium" or "high"` - The quality of the generated image. One of `low`, `medium`, `high`, - or `auto`. Default: `auto`. + High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. - `"low"` @@ -5812,904 +6829,925 @@ Learn when and how to compact long-running conversations in the [conversation st - `"high"` - - `"auto"` + - `user_location: optional object { type, city, country, 2 more }` - - `size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or "auto"` + The user's location. - The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. + - `type: "approximate"` - - `string` + The type of location approximation. Always `approximate`. - - `"1024x1024" or "1024x1536" or "1536x1024" or "auto"` + - `"approximate"` - The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. + - `city: optional string` - - `"1024x1024"` + Free text input for the city of the user, e.g. `San Francisco`. - - `"1024x1536"` + - `country: optional string` - - `"1536x1024"` + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - - `"auto"` + - `region: optional string` - - `LocalShell object { type }` + Free text input for the region of the user, e.g. `California`. - A tool that allows the model to execute shell commands in a local environment. + - `timezone: optional string` - - `type: "local_shell"` + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - The type of the local shell tool. Always `local_shell`. + - `ApplyPatch object { type, allowed_callers }` - - `"local_shell"` + Allows the assistant to create, delete, or update files using unified diffs. - - `Shell object { type, environment }` + - `type: "apply_patch"` - A tool that allows the model to execute shell commands. + The type of the tool. Always `apply_patch`. - - `type: "shell"` + - `"apply_patch"` - The type of the shell tool. Always `shell`. + - `allowed_callers: optional array of "direct" or "programmatic"` - - `"shell"` + The tool invocation context(s). - - `environment: optional ContainerAuto or LocalEnvironment or ContainerReference` + - `"direct"` - - `ContainerAuto object { type, file_ids, memory_limit, 2 more }` + - `"programmatic"` + + - `type: "tool_search_output"` + + The type of the item. Always `tool_search_output`. + + - `"tool_search_output"` - - `LocalEnvironment object { type, skills }` + - `created_by: optional string` - - `ContainerReference object { container_id, type }` + The identifier of the actor that created the item. - - `Custom object { name, type, defer_loading, 2 more }` + - `AdditionalTools object { id, role, tools, type }` - A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) + - `id: string` - - `name: string` + The unique ID of the additional tools item. - The name of the custom tool, used to identify it in tool calls. + - `role: "unknown" or "user" or "assistant" or 5 more` - - `type: "custom"` + The role that provided the additional tools. - The type of the custom tool. Always `custom`. + - `"unknown"` - - `"custom"` + - `"user"` - - `defer_loading: optional boolean` + - `"assistant"` - Whether this tool should be deferred and discovered via tool search. + - `"system"` - - `description: optional string` + - `"critic"` - Optional description of the custom tool, used to provide more context. + - `"discriminator"` - - `format: optional CustomToolInputFormat` + - `"developer"` - The input format for the custom tool. Default is unconstrained text. + - `"tool"` - - `Namespace object { description, name, tools, type }` + - `tools: array of object { name, parameters, strict, 5 more } or object { type, vector_store_ids, filters, 2 more } or object { type } or 13 more` - Groups function/custom tools under a shared namespace. + The additional tool definitions made available at this item. - - `description: string` + - `Function object { name, parameters, strict, 5 more }` - A description of the namespace shown to the model. + 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). - `name: string` - The namespace name used in tool calls (for example, `crm`). + The name of the function to call. - - `tools: array of object { name, type, defer_loading, 3 more } or object { name, type, defer_loading, 2 more }` + - `parameters: map[unknown]` - The function/custom tools available inside this namespace. + A JSON schema object describing the parameters of the function. - - `Function object { name, type, defer_loading, 3 more }` + - `strict: boolean` - - `name: string` + Whether strict parameter validation is enforced for this function tool. - `type: "function"` + The type of the function tool. Always `function`. + - `"function"` - - `defer_loading: optional boolean` + - `allowed_callers: optional array of "direct" or "programmatic"` - Whether this function should be deferred and discovered via tool search. + The tool invocation context(s). - - `description: optional string` + - `"direct"` - - `parameters: optional unknown` + - `"programmatic"` - - `strict: optional boolean` + - `defer_loading: optional boolean` - - `Custom object { name, type, defer_loading, 2 more }` + Whether this function is deferred and loaded via tool search. - A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) + - `description: optional string` - - `name: string` + A description of the function. Used by the model to determine whether or not to call the function. - The name of the custom tool, used to identify it in tool calls. + - `output_schema: optional map[unknown]` - - `type: "custom"` + A JSON schema object describing the JSON value encoded in string outputs for this function. - The type of the custom tool. Always `custom`. + - `FileSearch object { type, vector_store_ids, filters, 2 more }` - - `"custom"` + 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). - - `defer_loading: optional boolean` + - `type: "file_search"` - Whether this tool should be deferred and discovered via tool search. + The type of the file search tool. Always `file_search`. - - `description: optional string` + - `"file_search"` - Optional description of the custom tool, used to provide more context. + - `vector_store_ids: array of string` - - `format: optional CustomToolInputFormat` + The IDs of the vector stores to search. - The input format for the custom tool. Default is unconstrained text. + - `filters: optional ComparisonFilter or CompoundFilter` - - `type: "namespace"` + A filter to apply. - The type of the tool. Always `namespace`. + - `ComparisonFilter object { key, type, value }` - - `"namespace"` + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - - `ToolSearch object { type, description, execution, parameters }` + - `CompoundFilter object { filters, type }` - Hosted or BYOT tool search configuration for deferred tools. + Combine multiple filters using `and` or `or`. - - `type: "tool_search"` + - `max_num_results: optional number` - The type of the tool. Always `tool_search`. + The maximum number of results to return. This number should be between 1 and 50 inclusive. - - `"tool_search"` + - `ranking_options: optional object { hybrid_search, ranker, score_threshold }` - - `description: optional string` + Ranking options for search. - Description shown to the model for a client-executed tool search tool. + - `hybrid_search: optional object { embedding_weight, text_weight }` - - `execution: optional "server" or "client"` + Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. - Whether tool search is executed by the server or by the client. + - `embedding_weight: number` - - `"server"` + The weight of the embedding in the reciprocal ranking fusion. - - `"client"` + - `text_weight: number` - - `parameters: optional unknown` + The weight of the text in the reciprocal ranking fusion. - Parameter schema for a client-executed tool search tool. + - `ranker: optional "auto" or "default-2024-11-15"` - - `WebSearchPreview object { type, search_content_types, search_context_size, user_location }` + The ranker to use for the file search. - 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). + - `"auto"` - - `type: "web_search_preview" or "web_search_preview_2025_03_11"` + - `"default-2024-11-15"` - The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. + - `score_threshold: optional number` - - `"web_search_preview"` + The score threshold for the file search, a number between 0 and 1. Numbers closer to 1 will attempt to return only the most relevant results, but may return fewer results. - - `"web_search_preview_2025_03_11"` + - `Computer object { type }` - - `search_content_types: optional array of "text" or "image"` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `"text"` + - `type: "computer"` - - `"image"` + The type of the computer tool. Always `computer`. - - `search_context_size: optional "low" or "medium" or "high"` + - `"computer"` - High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. + - `ComputerUsePreview object { display_height, display_width, environment, type }` - - `"low"` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `"medium"` + - `display_height: number` - - `"high"` + The height of the computer display. - - `user_location: optional object { type, city, country, 2 more }` + - `display_width: number` - The user's location. + The width of the computer display. - - `type: "approximate"` + - `environment: "windows" or "mac" or "linux" or 2 more` - The type of location approximation. Always `approximate`. + The type of computer environment to control. - - `"approximate"` + - `"windows"` - - `city: optional string` + - `"mac"` - Free text input for the city of the user, e.g. `San Francisco`. + - `"linux"` - - `country: optional string` + - `"ubuntu"` - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + - `"browser"` - - `region: optional string` + - `type: "computer_use_preview"` - Free text input for the region of the user, e.g. `California`. + The type of the computer use tool. Always `computer_use_preview`. - - `timezone: optional string` + - `"computer_use_preview"` - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + - `WebSearch object { type, filters, search_context_size, user_location }` - - `ApplyPatch object { type }` + 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). - Allows the assistant to create, delete, or update files using unified diffs. + - `type: "web_search" or "web_search_2025_08_26"` - - `type: "apply_patch"` + The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. - The type of the tool. Always `apply_patch`. + - `"web_search"` - - `"apply_patch"` + - `"web_search_2025_08_26"` - - `type: "additional_tools"` + - `filters: optional object { allowed_domains }` - The type of the item. Always `additional_tools`. + Filters for the search. - - `"additional_tools"` + - `allowed_domains: optional array of string` - - `FunctionCallOutput object { call_id, output, type, 2 more }` + Allowed domains for the search. If not provided, all domains are allowed. + Subdomains of the provided domains are allowed as well. - The output of a function tool call. + Example: `["pubmed.ncbi.nlm.nih.gov"]` - - `call_id: string` + - `search_context_size: optional "low" or "medium" or "high"` - The unique ID of the function tool call generated by the model. + High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. - - `output: string or array of ResponseInputText or ResponseInputImage or ResponseInputFile` + - `"low"` - The output from the function call generated by your code. - Can be a string or an list of output content. + - `"medium"` - - `StringOutput = string` + - `"high"` - A string of the output of the function call. + - `user_location: optional object { city, country, region, 2 more }` - - `OutputContentList = array of ResponseInputText or ResponseInputImage or ResponseInputFile` + The approximate location of the user. - Text, image, or file output of the function call. + - `city: optional string` - - `ResponseInputText object { text, type }` + Free text input for the city of the user, e.g. `San Francisco`. - A text input to the model. + - `country: optional string` - - `ResponseInputImage object { detail, type, file_id, image_url }` + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - An image input to the model. Learn about [image inputs](/docs/guides/vision). + - `region: optional string` - - `ResponseInputFile object { type, detail, file_data, 3 more }` + Free text input for the region of the user, e.g. `California`. - A file input to the model. + - `timezone: optional string` - - `type: "function_call_output"` + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - The type of the function tool call output. Always `function_call_output`. + - `type: optional "approximate"` - - `"function_call_output"` + The type of location approximation. Always `approximate`. - - `id: optional string` + - `"approximate"` - The unique ID of the function tool call output. Populated when this item - is returned via API. + - `Mcp object { server_label, type, allowed_callers, 9 more }` - - `status: optional "in_progress" or "completed" or "incomplete"` + 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). - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `server_label: string` - - `"in_progress"` + A label for this MCP server, used to identify it in tool calls. - - `"completed"` + - `type: "mcp"` - - `"incomplete"` + The type of the MCP tool. Always `mcp`. - - `FileSearchCall object { id, queries, status, 2 more }` + - `"mcp"` - The results of a file search tool call. See the - [file search guide](/docs/guides/tools-file-search) for more information. + - `allowed_callers: optional array of "direct" or "programmatic"` - - `id: string` + The tool invocation context(s). - The unique ID of the file search tool call. + - `"direct"` - - `queries: array of string` + - `"programmatic"` - The queries used to search for files. + - `allowed_tools: optional array of string or object { read_only, tool_names }` - - `status: "in_progress" or "searching" or "completed" or 2 more` + List of allowed tool names or a filter object. - The status of the file search tool call. One of `in_progress`, - `searching`, `incomplete` or `failed`, + - `McpAllowedTools = array of string` - - `"in_progress"` + A string array of allowed tool names - - `"searching"` + - `McpToolFilter object { read_only, tool_names }` - - `"completed"` + A filter object to specify which tools are allowed. - - `"incomplete"` + - `read_only: optional boolean` - - `"failed"` + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. - - `type: "file_search_call"` + - `tool_names: optional array of string` - The type of the file search tool call. Always `file_search_call`. + List of allowed tool names. - - `"file_search_call"` + - `authorization: optional string` - - `results: optional array of object { attributes, file_id, filename, 2 more }` + An OAuth access token that can be used with a remote MCP server, either + with a custom MCP server URL or a service connector. Your application + must handle the OAuth authorization flow and provide the token here. - The results of the file search tool call. + - `connector_id: optional "connector_dropbox" or "connector_gmail" or "connector_googlecalendar" or 5 more` - - `attributes: optional map[string or number or boolean]` + Identifier for service connectors, like those available in ChatGPT. One of + `server_url`, `connector_id`, or `tunnel_id` must be provided. Learn more + about service connectors [here](https://platform.openai.com/docs/guides/tools-remote-mcp#connectors). - Set of 16 key-value pairs that can be attached to an object. This can be - useful for storing additional information about the object in a structured - format, and querying for objects via API or the dashboard. Keys are strings - with a maximum length of 64 characters. Values are strings with a maximum - length of 512 characters, booleans, or numbers. + Currently supported `connector_id` values are: - - `string` + - Dropbox: `connector_dropbox` + - Gmail: `connector_gmail` + - Google Calendar: `connector_googlecalendar` + - Google Drive: `connector_googledrive` + - Microsoft Teams: `connector_microsoftteams` + - Outlook Calendar: `connector_outlookcalendar` + - Outlook Email: `connector_outlookemail` + - SharePoint: `connector_sharepoint` - - `number` + - `"connector_dropbox"` - - `boolean` + - `"connector_gmail"` - - `file_id: optional string` + - `"connector_googlecalendar"` - The unique ID of the file. + - `"connector_googledrive"` - - `filename: optional string` + - `"connector_microsoftteams"` - The name of the file. + - `"connector_outlookcalendar"` - - `score: optional number` + - `"connector_outlookemail"` - The relevance score of the file - a value between 0 and 1. + - `"connector_sharepoint"` - - `text: optional string` + - `defer_loading: optional boolean` - The text that was retrieved from the file. + Whether this MCP tool is deferred and discovered via tool search. - - `WebSearchCall object { id, action, status, type }` + - `headers: optional map[string]` - The results of a web search tool call. See the - [web search guide](/docs/guides/tools-web-search) for more information. + Optional HTTP headers to send to the MCP server. Use for authentication + or other purposes. - - `id: string` + - `require_approval: optional object { always, never } or "always" or "never"` - The unique ID of the web search tool call. + Specify which of the MCP server's tools require approval. - - `action: object { type, queries, query, sources } or object { type, url } or object { pattern, type, url }` + - `McpToolApprovalFilter object { always, never }` - An object describing the specific action taken in this web search call. - Includes details on how the model used the web (search, open_page, find_in_page). + Specify which of the MCP server's tools require approval. Can be + `always`, `never`, or a filter object associated with tools + that require approval. - - `Search object { type, queries, query, sources }` + - `always: optional object { read_only, tool_names }` - Action type "search" - Performs a web search query. + A filter object to specify which tools are allowed. - - `type: "search"` + - `read_only: optional boolean` - The action type. + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. - - `"search"` + - `tool_names: optional array of string` - - `queries: optional array of string` + List of allowed tool names. - The search queries. + - `never: optional object { read_only, tool_names }` - - `query: optional string` + A filter object to specify which tools are allowed. - The search query. + - `read_only: optional boolean` - - `sources: optional array of object { type, url }` + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. - The sources used in the search. + - `tool_names: optional array of string` - - `type: "url"` + List of allowed tool names. - The type of source. Always `url`. + - `McpToolApprovalSetting = "always" or "never"` - - `"url"` + Specify a single approval policy for all tools. One of `always` or + `never`. When set to `always`, all tools will require approval. When + set to `never`, all tools will not require approval. - - `url: string` + - `"always"` - The URL of the source. + - `"never"` - - `OpenPage object { type, url }` + - `server_description: optional string` - Action type "open_page" - Opens a specific URL from search results. + Optional description of the MCP server, used to provide more context. - - `type: "open_page"` + - `server_url: optional string` - The action type. + The URL for the MCP server. One of `server_url`, `connector_id`, or + `tunnel_id` must be provided. - - `"open_page"` + - `tunnel_id: optional string` - - `url: optional string` + The Secure MCP Tunnel ID to use instead of a direct server URL. One of + `server_url`, `connector_id`, or `tunnel_id` must be provided. - The URL opened by the model. + - `CodeInterpreter object { container, type, allowed_callers }` - - `FindInPage object { pattern, type, url }` + A tool that runs Python code to help generate a response to a prompt. - Action type "find_in_page": Searches for a pattern within a loaded page. + - `container: string or object { type, file_ids, memory_limit, network_policy }` - - `pattern: string` + The code interpreter container. Can be a container ID or an object that + specifies uploaded file IDs to make available to your code, along with an + optional `memory_limit` setting. - The pattern or text to search for within the page. + - `string` - - `type: "find_in_page"` + The container ID. - The action type. + - `CodeInterpreterToolAuto object { type, file_ids, memory_limit, network_policy }` - - `"find_in_page"` + Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. - - `url: string` + - `type: "auto"` - The URL of the page searched for the pattern. + Always `auto`. - - `status: "in_progress" or "searching" or "completed" or "failed"` + - `"auto"` - The status of the web search tool call. + - `file_ids: optional array of string` - - `"in_progress"` + An optional list of uploaded files to make available to your code. - - `"searching"` + - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` - - `"completed"` + The memory limit for the code interpreter container. - - `"failed"` + - `"1g"` - - `type: "web_search_call"` + - `"4g"` - The type of the web search tool call. Always `web_search_call`. + - `"16g"` - - `"web_search_call"` + - `"64g"` - - `ImageGenerationCall object { id, result, status, type }` + - `network_policy: optional ContainerNetworkPolicyDisabled or ContainerNetworkPolicyAllowlist` - An image generation request made by the model. + Network access policy for the container. - - `id: string` + - `ContainerNetworkPolicyDisabled object { type }` - The unique ID of the image generation call. + - `ContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` - - `result: string` + - `type: "code_interpreter"` - The generated image encoded in base64. + The type of the code interpreter tool. Always `code_interpreter`. - - `status: "in_progress" or "completed" or "generating" or "failed"` + - `"code_interpreter"` - The status of the image generation call. + - `allowed_callers: optional array of "direct" or "programmatic"` - - `"in_progress"` + The tool invocation context(s). - - `"completed"` + - `"direct"` - - `"generating"` + - `"programmatic"` - - `"failed"` + - `ProgrammaticToolCalling object { type }` - - `type: "image_generation_call"` + - `type: "programmatic_tool_calling"` - The type of the image generation call. Always `image_generation_call`. + The type of the tool. Always `programmatic_tool_calling`. - - `"image_generation_call"` + - `"programmatic_tool_calling"` - - `ComputerCall object { id, call_id, pending_safety_checks, 4 more }` + - `ImageGeneration object { type, action, background, 9 more }` - A tool call to a computer use tool. See the - [computer use guide](/docs/guides/tools-computer-use) for more information. + A tool that generates images using the GPT image models. - - `id: string` + - `type: "image_generation"` - The unique ID of the computer call. + The type of the image generation tool. Always `image_generation`. - - `call_id: string` + - `"image_generation"` - An identifier used when responding to the tool call with output. + - `action: optional "generate" or "edit" or "auto"` - - `pending_safety_checks: array of object { id, code, message }` + Whether to generate a new image or edit an existing image. Default: `auto`. - The pending safety checks for the computer call. + - `"generate"` - - `id: string` + - `"edit"` - The ID of the pending safety check. + - `"auto"` - - `code: optional string` + - `background: optional "transparent" or "opaque" or "auto"` - The type of the pending safety check. + Allows to set transparency for the background of the generated image(s). + This parameter is only supported for GPT image models that support + transparent backgrounds. Must be one of `transparent`, `opaque`, or + `auto` (default value). When `auto` is used, the model will + automatically determine the best background for the image. - - `message: optional string` + `gpt-image-2` and `gpt-image-2-2026-04-21` do not support + transparent backgrounds. Requests with `background` set to + `transparent` will return an error for these models; use `opaque` or + `auto` instead. - Details about the pending safety check. + If `transparent`, the output format needs to support transparency, + so it should be set to either `png` (default value) or `webp`. - - `status: "in_progress" or "completed" or "incomplete"` + - `"transparent"` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `"opaque"` - - `"in_progress"` + - `"auto"` - - `"completed"` + - `input_fidelity: optional "high" or "low"` - - `"incomplete"` + Control how much effort the model will exert to match the style and features, especially facial features, of input images. This parameter is only supported for `gpt-image-1` and `gpt-image-1.5` and later models, unsupported for `gpt-image-1-mini`. Supports `high` and `low`. Defaults to `low`. - - `type: "computer_call"` + - `"high"` - The type of the computer call. Always `computer_call`. + - `"low"` - - `"computer_call"` + - `input_image_mask: optional object { file_id, image_url }` - - `action: optional ComputerAction` + Optional mask for inpainting. Contains `image_url` + (string, optional) and `file_id` (string, optional). - A click action. + - `file_id: optional string` - - `Click object { button, type, x, 2 more }` + File ID for the mask image. - A click action. + - `image_url: optional string` - - `button: "left" or "right" or "wheel" or 2 more` + Base64-encoded mask image. - Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. + - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-2" or 3 more` - - `"left"` + The image generation model to use. Default: `gpt-image-1`. - - `"right"` + - `string` - - `"wheel"` + - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-2" or 3 more` - - `"back"` + The image generation model to use. Default: `gpt-image-1`. - - `"forward"` + - `"gpt-image-1"` - - `type: "click"` + - `"gpt-image-1-mini"` - Specifies the event type. For a click action, this property is always `click`. + - `"gpt-image-2"` - - `"click"` + - `"gpt-image-2-2026-04-21"` - - `x: number` + - `"gpt-image-1.5"` - The x-coordinate where the click occurred. + - `"chatgpt-image-latest"` - - `y: number` + - `moderation: optional "auto" or "low"` - The y-coordinate where the click occurred. + Moderation level for the generated image. Default: `auto`. - - `keys: optional array of string` + - `"auto"` - The keys being held while clicking. + - `"low"` - - `DoubleClick object { keys, type, x, y }` + - `output_compression: optional number` - A double click action. + Compression level for the output image. Default: 100. - - `keys: array of string` + - `output_format: optional "png" or "webp" or "jpeg"` - The keys being held while double-clicking. + The output format of the generated image. One of `png`, `webp`, or + `jpeg`. Default: `png`. - - `type: "double_click"` + - `"png"` - Specifies the event type. For a double click action, this property is always set to `double_click`. + - `"webp"` - - `"double_click"` + - `"jpeg"` - - `x: number` + - `partial_images: optional number` - The x-coordinate where the double click occurred. + Number of partial images to generate in streaming mode, from 0 (default value) to 3. - - `y: number` + - `quality: optional "low" or "medium" or "high" or "auto"` - The y-coordinate where the double click occurred. + The quality of the generated image. One of `low`, `medium`, `high`, + or `auto`. Default: `auto`. - - `Drag object { path, type, keys }` + - `"low"` - A drag action. + - `"medium"` - - `path: array of object { x, y }` + - `"high"` - An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg + - `"auto"` - ``` - [ - { x: 100, y: 200 }, - { x: 200, y: 300 } - ] - ``` + - `size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or "auto"` - - `x: number` + The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. - The x-coordinate. + - `string` - - `y: number` + - `"1024x1024" or "1024x1536" or "1536x1024" or "auto"` - The y-coordinate. + The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. - - `type: "drag"` + - `"1024x1024"` - Specifies the event type. For a drag action, this property is always set to `drag`. + - `"1024x1536"` - - `"drag"` + - `"1536x1024"` - - `keys: optional array of string` + - `"auto"` - The keys being held while dragging the mouse. + - `LocalShell object { type }` - - `Keypress object { keys, type }` + A tool that allows the model to execute shell commands in a local environment. - A collection of keypresses the model would like to perform. + - `type: "local_shell"` - - `keys: array of string` + The type of the local shell tool. Always `local_shell`. - The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. + - `"local_shell"` - - `type: "keypress"` + - `Shell object { type, allowed_callers, environment }` - Specifies the event type. For a keypress action, this property is always set to `keypress`. + A tool that allows the model to execute shell commands. - - `"keypress"` + - `type: "shell"` - - `Move object { type, x, y, keys }` + The type of the shell tool. Always `shell`. - A mouse move action. + - `"shell"` - - `type: "move"` + - `allowed_callers: optional array of "direct" or "programmatic"` - Specifies the event type. For a move action, this property is always set to `move`. + The tool invocation context(s). - - `"move"` + - `"direct"` - - `x: number` + - `"programmatic"` - The x-coordinate to move to. + - `environment: optional ContainerAuto or LocalEnvironment or ContainerReference` - - `y: number` + - `ContainerAuto object { type, file_ids, memory_limit, 2 more }` - The y-coordinate to move to. + - `LocalEnvironment object { type, skills }` - - `keys: optional array of string` + - `ContainerReference object { container_id, type }` - The keys being held while moving the mouse. + - `Custom object { name, type, allowed_callers, 3 more }` - - `Screenshot object { type }` + 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) - A screenshot action. + - `name: string` - - `type: "screenshot"` + The name of the custom tool, used to identify it in tool calls. - Specifies the event type. For a screenshot action, this property is always set to `screenshot`. + - `type: "custom"` - - `"screenshot"` + The type of the custom tool. Always `custom`. - - `Scroll object { scroll_x, scroll_y, type, 3 more }` + - `"custom"` - A scroll action. + - `allowed_callers: optional array of "direct" or "programmatic"` - - `scroll_x: number` + The tool invocation context(s). - The horizontal scroll distance. + - `"direct"` - - `scroll_y: number` + - `"programmatic"` - The vertical scroll distance. + - `defer_loading: optional boolean` - - `type: "scroll"` + Whether this tool should be deferred and discovered via tool search. - Specifies the event type. For a scroll action, this property is always set to `scroll`. + - `description: optional string` - - `"scroll"` + Optional description of the custom tool, used to provide more context. - - `x: number` + - `format: optional CustomToolInputFormat` - The x-coordinate where the scroll occurred. + The input format for the custom tool. Default is unconstrained text. - - `y: number` + - `Namespace object { description, name, tools, type }` - The y-coordinate where the scroll occurred. + Groups function/custom tools under a shared namespace. - - `keys: optional array of string` + - `description: string` - The keys being held while scrolling. + A description of the namespace shown to the model. - - `Type object { text, type }` + - `name: string` - An action to type in text. + The namespace name used in tool calls (for example, `crm`). - - `text: string` + - `tools: array of object { name, type, allowed_callers, 5 more } or object { name, type, allowed_callers, 3 more }` - The text to type. + The function/custom tools available inside this namespace. - - `type: "type"` + - `Function object { name, type, allowed_callers, 5 more }` - Specifies the event type. For a type action, this property is always set to `type`. + - `name: string` - - `"type"` + - `type: "function"` - - `Wait object { type }` + - `"function"` - A wait action. + - `allowed_callers: optional array of "direct" or "programmatic"` - - `type: "wait"` + The tool invocation context(s). - Specifies the event type. For a wait action, this property is always set to `wait`. + - `"direct"` - - `"wait"` + - `"programmatic"` - - `actions: optional ComputerActionList` + - `defer_loading: optional boolean` - Flattened batched actions for `computer_use`. Each action includes an - `type` discriminator and action-specific fields. + Whether this function should be deferred and discovered via tool search. - - `Click object { button, type, x, 2 more }` + - `description: optional string` - A click action. + - `output_schema: optional map[unknown]` - - `DoubleClick object { keys, type, x, y }` + A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. - A double click action. + - `parameters: optional unknown` - - `Drag object { path, type, keys }` + - `strict: optional boolean` - A drag action. + 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. - - `Keypress object { keys, type }` + - `Custom object { name, type, allowed_callers, 3 more }` - A collection of keypresses the model would like to perform. + 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) - - `Move object { type, x, y, keys }` + - `name: string` - A mouse move action. + The name of the custom tool, used to identify it in tool calls. - - `Screenshot object { type }` + - `type: "custom"` - A screenshot action. + The type of the custom tool. Always `custom`. - - `Scroll object { scroll_x, scroll_y, type, 3 more }` + - `"custom"` - A scroll action. + - `allowed_callers: optional array of "direct" or "programmatic"` - - `Type object { text, type }` + The tool invocation context(s). - An action to type in text. + - `"direct"` - - `Wait object { type }` + - `"programmatic"` - A wait action. + - `defer_loading: optional boolean` - - `ComputerCallOutput object { id, call_id, output, 4 more }` + Whether this tool should be deferred and discovered via tool search. - - `id: string` + - `description: optional string` - The unique ID of the computer call tool output. + Optional description of the custom tool, used to provide more context. - - `call_id: string` + - `format: optional CustomToolInputFormat` - The ID of the computer tool call that produced the output. + The input format for the custom tool. Default is unconstrained text. - - `output: ResponseComputerToolCallOutputScreenshot` + - `type: "namespace"` - A computer screenshot image used with the computer use tool. + The type of the tool. Always `namespace`. - - `type: "computer_screenshot"` + - `"namespace"` - Specifies the event type. For a computer screenshot, this property is - always set to `computer_screenshot`. + - `ToolSearch object { type, description, execution, parameters }` - - `"computer_screenshot"` + Hosted or BYOT tool search configuration for deferred tools. - - `file_id: optional string` + - `type: "tool_search"` - The identifier of an uploaded file that contains the screenshot. + The type of the tool. Always `tool_search`. - - `image_url: optional string` + - `"tool_search"` - The URL of the screenshot image. + - `description: optional string` - - `status: "completed" or "incomplete" or "failed" or "in_progress"` + Description shown to the model for a client-executed tool search tool. - The status of the message input. One of `in_progress`, `completed`, or - `incomplete`. Populated when input items are returned via API. + - `execution: optional "server" or "client"` - - `"completed"` + Whether tool search is executed by the server or by the client. - - `"incomplete"` + - `"server"` - - `"failed"` + - `"client"` - - `"in_progress"` + - `parameters: optional unknown` - - `type: "computer_call_output"` + Parameter schema for a client-executed tool search tool. - The type of the computer tool call output. Always `computer_call_output`. + - `WebSearchPreview object { type, search_content_types, search_context_size, user_location }` - - `"computer_call_output"` + 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). - - `acknowledged_safety_checks: optional array of object { id, code, message }` + - `type: "web_search_preview" or "web_search_preview_2025_03_11"` - The safety checks reported by the API that have been acknowledged by the - developer. + The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. - - `id: string` + - `"web_search_preview"` - The ID of the pending safety check. + - `"web_search_preview_2025_03_11"` - - `code: optional string` + - `search_content_types: optional array of "text" or "image"` - The type of the pending safety check. + - `"text"` - - `message: optional string` + - `"image"` - Details about the pending safety check. + - `search_context_size: optional "low" or "medium" or "high"` - - `created_by: optional string` + High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. - The identifier of the actor that created the item. + - `"low"` - - `Reasoning object { id, summary, type, 3 more }` + - `"medium"` - A description of the chain of thought used by a reasoning model while generating - a response. Be sure to include these items in your `input` to the Responses API - for subsequent turns of a conversation if you are manually - [managing context](/docs/guides/conversation-state). + - `"high"` - - `id: string` + - `user_location: optional object { type, city, country, 2 more }` - The unique identifier of the reasoning content. + The user's location. - - `summary: array of SummaryTextContent` + - `type: "approximate"` - Reasoning summary content. + The type of location approximation. Always `approximate`. - - `text: string` + - `"approximate"` - A summary of the reasoning output from the model so far. + - `city: optional string` - - `type: "summary_text"` + Free text input for the city of the user, e.g. `San Francisco`. - The type of the object. Always `summary_text`. + - `country: optional string` - - `type: "reasoning"` + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - The type of the object. Always `reasoning`. + - `region: optional string` - - `"reasoning"` + Free text input for the region of the user, e.g. `California`. - - `content: optional array of object { text, type }` + - `timezone: optional string` - Reasoning text content. + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - - `text: string` + - `ApplyPatch object { type, allowed_callers }` - The reasoning text from the model. + Allows the assistant to create, delete, or update files using unified diffs. - - `type: "reasoning_text"` + - `type: "apply_patch"` - The type of the reasoning text. Always `reasoning_text`. + The type of the tool. Always `apply_patch`. - - `"reasoning_text"` + - `"apply_patch"` - - `encrypted_content: optional string` + - `allowed_callers: optional array of "direct" or "programmatic"` - The encrypted content of the reasoning item - populated when a response is - generated with `reasoning.encrypted_content` in the `include` parameter. + The tool invocation context(s). - - `status: optional "in_progress" or "completed" or "incomplete"` + - `"direct"` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `"programmatic"` - - `"in_progress"` + - `type: "additional_tools"` - - `"completed"` + The type of the item. Always `additional_tools`. - - `"incomplete"` + - `"additional_tools"` - `Compaction object { id, encrypted_content, type, created_by }` - A compaction item generated by the [`v1/responses/compact` API](/docs/api-reference/responses/compact). + A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). - `id: string` @@ -6729,6 +7767,36 @@ Learn when and how to compact long-running conversations in the [conversation st The identifier of the actor that created the item. + - `ImageGenerationCall object { id, result, status, type }` + + An image generation request made by the model. + + - `id: string` + + The unique ID of the image generation call. + + - `result: string` + + The generated image encoded in base64. + + - `status: "in_progress" or "completed" or "generating" or "failed"` + + The status of the image generation call. + + - `"in_progress"` + + - `"completed"` + + - `"generating"` + + - `"failed"` + + - `type: "image_generation_call"` + + The type of the image generation call. Always `image_generation_call`. + + - `"image_generation_call"` + - `CodeInterpreterCall object { id, code, container_id, 3 more }` A tool call to run code. @@ -6884,7 +7952,7 @@ Learn when and how to compact long-running conversations in the [conversation st - `"incomplete"` - - `ShellCall object { id, action, call_id, 4 more }` + - `ShellCall object { id, action, call_id, 5 more }` A tool call that executes one or more shell commands in a managed environment. @@ -6952,11 +8020,31 @@ Learn when and how to compact long-running conversations in the [conversation st - `"shell_call"` + - `caller: optional object { type } or object { caller_id, type }` + + The execution context that produced this tool call. + + - `Direct object { type }` + + - `type: "direct"` + + - `"direct"` + + - `Program object { caller_id, type }` + + - `caller_id: string` + + The call ID of the program item that produced this tool call. + + - `type: "program"` + + - `"program"` + - `created_by: optional string` The ID of the entity that created this tool call. - - `ShellCallOutput object { id, call_id, max_output_length, 4 more }` + - `ShellCallOutput object { id, call_id, max_output_length, 5 more }` The output of a shell tool call that was emitted. @@ -7032,11 +8120,31 @@ Learn when and how to compact long-running conversations in the [conversation st - `"shell_call_output"` + - `caller: optional object { type } or object { caller_id, type }` + + The execution context that produced this tool call. + + - `Direct object { type }` + + - `type: "direct"` + + - `"direct"` + + - `Program object { caller_id, type }` + + - `caller_id: string` + + The call ID of the program item that produced this tool call. + + - `type: "program"` + + - `"program"` + - `created_by: optional string` The identifier of the actor that created the item. - - `ApplyPatchCall object { id, call_id, operation, 3 more }` + - `ApplyPatchCall object { id, call_id, operation, 4 more }` A tool call that applies file diffs by creating, deleting, or updating files. @@ -7116,11 +8224,31 @@ Learn when and how to compact long-running conversations in the [conversation st - `"apply_patch_call"` + - `caller: optional object { type } or object { caller_id, type }` + + The execution context that produced this tool call. + + - `Direct object { type }` + + - `type: "direct"` + + - `"direct"` + + - `Program object { caller_id, type }` + + - `caller_id: string` + + The call ID of the program item that produced this tool call. + + - `type: "program"` + + - `"program"` + - `created_by: optional string` The ID of the entity that created this tool call. - - `ApplyPatchCallOutput object { id, call_id, status, 3 more }` + - `ApplyPatchCallOutput object { id, call_id, status, 4 more }` The output emitted by an apply patch tool call. @@ -7146,6 +8274,26 @@ Learn when and how to compact long-running conversations in the [conversation st - `"apply_patch_call_output"` + - `caller: optional object { type } or object { caller_id, type }` + + The execution context that produced this tool call. + + - `Direct object { type }` + + - `type: "direct"` + + - `"direct"` + + - `Program object { caller_id, type }` + + - `caller_id: string` + + The call ID of the program item that produced this tool call. + + - `type: "program"` + + - `"program"` + - `created_by: optional string` The ID of the entity that created this tool call output. @@ -7154,6 +8302,59 @@ Learn when and how to compact long-running conversations in the [conversation st Optional textual output returned by the apply patch tool. + - `McpCall object { id, arguments, name, 6 more }` + + An invocation of a tool on an MCP server. + + - `id: string` + + The unique ID of the tool call. + + - `arguments: string` + + A JSON string of the arguments passed to the tool. + + - `name: string` + + The name of the tool that was run. + + - `server_label: string` + + The label of the MCP server running the tool. + + - `type: "mcp_call"` + + The type of the item. Always `mcp_call`. + + - `"mcp_call"` + + - `approval_request_id: optional string` + + Unique identifier for the MCP tool call approval request. + Include this value in a subsequent `mcp_approval_response` input to approve or reject the corresponding tool call. + + - `error: optional string` + + The error from the tool call, if any. + + - `output: optional string` + + The output from the tool call. + + - `status: optional "in_progress" or "completed" or "incomplete" or 2 more` + + The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `"calling"` + + - `"failed"` + - `McpListTools object { id, server_label, tools, 2 more }` A list of tools available on an MCP server. @@ -7248,60 +8449,7 @@ Learn when and how to compact long-running conversations in the [conversation st Optional reason for the decision. - - `McpCall object { id, arguments, name, 6 more }` - - An invocation of a tool on an MCP server. - - - `id: string` - - The unique ID of the tool call. - - - `arguments: string` - - A JSON string of the arguments passed to the tool. - - - `name: string` - - The name of the tool that was run. - - - `server_label: string` - - The label of the MCP server running the tool. - - - `type: "mcp_call"` - - The type of the item. Always `mcp_call`. - - - `"mcp_call"` - - - `approval_request_id: optional string` - - Unique identifier for the MCP tool call approval request. - Include this value in a subsequent `mcp_approval_response` input to approve or reject the corresponding tool call. - - - `error: optional string` - - The error from the tool call, if any. - - - `output: optional string` - - The output from the tool call. - - - `status: optional "in_progress" or "completed" or "incomplete" or 2 more` - - The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. - - - `"in_progress"` - - - `"completed"` - - - `"incomplete"` - - - `"calling"` - - - `"failed"` - - - `CustomToolCall object { call_id, input, name, 3 more }` + - `CustomToolCall object { call_id, input, name, 4 more }` A call to a custom tool created by the model. @@ -7327,13 +8475,35 @@ 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: optional object { type } or object { caller_id, type }` + + The execution context that produced this tool call. + + - `Direct object { type }` + + - `type: "direct"` + + - `"direct"` + + - `Program object { caller_id, type }` + + - `caller_id: string` + + The call ID of the program item that produced this tool call. + + - `type: "program"` + + - `"program"` + - `namespace: optional string` The namespace of the custom tool being called. - - `CustomToolCallOutput object { call_id, output, type, id }` + - `CustomToolCallOutput object { id, call_id, output, 4 more }` - The output of a custom tool call from your code, being sent back to the model. + - `id: string` + + The unique ID of the custom tool call output item. - `call_id: string` @@ -7352,27 +8522,62 @@ Learn when and how to compact long-running conversations in the [conversation st Text, image, or file output of the custom tool call. - - `ResponseInputText object { text, type }` + - `ResponseInputText object { text, type, prompt_cache_breakpoint }` A text input to the model. - - `ResponseInputImage object { detail, type, file_id, image_url }` + - `ResponseInputImage object { detail, type, file_id, 2 more }` - An image input to the model. Learn about [image inputs](/docs/guides/vision). + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - `ResponseInputFile object { type, detail, file_data, 3 more }` + - `ResponseInputFile object { type, detail, file_data, 4 more }` A file input to the model. + - `status: "in_progress" or "completed" or "incomplete"` + + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + - `type: "custom_tool_call_output"` The type of the custom tool call output. Always `custom_tool_call_output`. - `"custom_tool_call_output"` - - `id: optional string` + - `caller: optional object { type } or object { caller_id, type }` - The unique ID of the custom tool call output in the OpenAI platform. + The execution context that produced this tool call. + + - `Direct object { type }` + + - `type: "direct"` + + The caller type. Always `direct`. + + - `"direct"` + + - `Program object { caller_id, type }` + + - `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: optional string` + + The identifier of the actor that created the item. - `usage: ResponseUsage` @@ -7382,14 +8587,18 @@ Learn when and how to compact long-running conversations in the [conversation st The number of input tokens. - - `input_tokens_details: object { cached_tokens }` + - `input_tokens_details: object { cache_write_tokens, cached_tokens }` A detailed breakdown of the input tokens. + - `cache_write_tokens: number` + + The number of input tokens that were written to the cache. + - `cached_tokens: number` The number of tokens that were retrieved from the cache. - [More on prompt caching](/docs/guides/prompt-caching). + [More on prompt caching](https://platform.openai.com/docs/guides/prompt-caching). - `output_tokens: number` @@ -7414,7 +8623,7 @@ curl https://api.openai.com/v1/responses/compact \ -H 'Content-Type: application/json' \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -d '{ - "model": "gpt-5.4", + "model": "gpt-5.6-sol", "previous_response_id": "resp_123" }' ``` @@ -7431,11 +8640,37 @@ curl https://api.openai.com/v1/responses/compact \ "id": "id", "content": [ { + "annotations": [ + { + "file_id": "file_id", + "filename": "filename", + "index": 0, + "type": "file_citation" + } + ], "text": "text", - "type": "input_text" + "type": "output_text", + "logprobs": [ + { + "token": "token", + "bytes": [ + 0 + ], + "logprob": 0, + "top_logprobs": [ + { + "token": "token", + "bytes": [ + 0 + ], + "logprob": 0 + } + ] + } + ] } ], - "role": "unknown", + "role": "assistant", "status": "in_progress", "type": "message", "phase": "commentary" @@ -7444,6 +8679,7 @@ curl https://api.openai.com/v1/responses/compact \ "usage": { "input_tokens": 0, "input_tokens_details": { + "cache_write_tokens": 0, "cached_tokens": 0 }, "output_tokens": 0,