diff --git a/en/resources/responses/methods/compact/index.md b/en/resources/responses/methods/compact/index.md index fb6858d5..755b31d1 100644 --- a/en/resources/responses/methods/compact/index.md +++ b/en/resources/responses/methods/compact/index.md @@ -2,17 +2,19 @@ **post** `/responses/compact` -Compact a response +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). ### Body Parameters - `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. + 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" 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"` @@ -266,7 +268,7 @@ Compact a response - `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). + An image input to the model. Learn about [image inputs](/docs/guides/vision). - `detail: "low" or "high" or "auto" or "original"` @@ -429,7 +431,7 @@ Compact a response The content of the output message. - - `ResponseOutputText object { annotations, text, type, logprobs }` + - `ResponseOutputText object { annotations, logprobs, text, type }` A text output from the model. @@ -533,17 +535,7 @@ Compact a response - `"file_path"` - - `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 }` + - `logprobs: array of object { token, bytes, logprob, top_logprobs }` - `token: string` @@ -559,6 +551,16 @@ Compact a response - `logprob: number` + - `text: string` + + The text output from the model. + + - `type: "output_text"` + + The type of the output text. Always `output_text`. + + - `"output_text"` + - `ResponseOutputRefusal object { refusal, type }` A refusal from the model. @@ -609,7 +611,7 @@ Compact a response - `FileSearchCall object { id, queries, status, 2 more }` 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. + [file search guide](/docs/guides/tools-file-search) for more information. - `id: string` @@ -677,7 +679,7 @@ Compact a response - `ComputerCall object { id, call_id, pending_safety_checks, 4 more }` 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. + [computer use guide](/docs/guides/tools-computer-use) for more information. - `id: string` @@ -720,7 +722,7 @@ Compact a response - `"computer_call"` - - `action: optional object { button, type, x, 2 more } or object { keys, type, x, y } or object { path, type, keys } or 6 more` + - `action: optional ComputerAction` A click action. @@ -924,193 +926,38 @@ Compact a response 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. @@ -1177,7 +1024,7 @@ Compact a response - `WebSearchCall object { id, action, status, type }` 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. + [web search guide](/docs/guides/tools-web-search) for more information. - `id: string` @@ -1273,7 +1120,7 @@ Compact a response - `FunctionCall object { arguments, call_id, name, 5 more }` A tool call to run a function. See the - [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. + [function calling guide](/docs/guides/function-calling) for more information. - `arguments: string` @@ -1340,7 +1187,7 @@ Compact a response The unique ID of the function tool call generated by the model. - - `output: string or ResponseFunctionCallOutputItemList` + - `output: string or array of ResponseInputTextContent or ResponseInputImageContent or ResponseInputFileContent` Text, image, or file output of the function tool call. @@ -1348,7 +1195,7 @@ Compact a response A JSON string of the output of the function tool call. - - `ResponseFunctionCallOutputItemList = array of ResponseFunctionCallOutputItem` + - `array of ResponseInputTextContent or ResponseInputImageContent or ResponseInputFileContent` An array of content outputs (text, image, file) for the function tool call. @@ -1378,7 +1225,7 @@ Compact a response - `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) + An image input to the model. Learn about [image inputs](/docs/guides/vision) - `type: "input_image"` @@ -1762,7 +1609,7 @@ Compact a response - `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](https://platform.openai.com/docs/guides/tools-web-search). + [web search tool](/docs/guides/tools-web-search). - `type: "web_search" or "web_search_2025_08_26"` @@ -1822,7 +1669,7 @@ Compact a response - `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](https://platform.openai.com/docs/guides/tools-remote-mcp). + (MCP) servers. [Learn more about MCP](/docs/guides/tools-remote-mcp). - `server_label: string` @@ -1874,7 +1721,7 @@ Compact a response 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). + about service connectors [here](/docs/guides/tools-remote-mcp#connectors). Currently supported `connector_id` values are: @@ -2098,19 +1945,8 @@ Compact a response - `background: optional "transparent" or "opaque" or "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`. + Background type for the generated image. One of `transparent`, + `opaque`, or `auto`. Default: `auto`. - `"transparent"` @@ -2139,13 +1975,13 @@ Compact a response Base64-encoded mask image. - - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-2" or 3 more` + - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` The image generation model to use. Default: `gpt-image-1`. - `string` - - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-2" or 3 more` + - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` The image generation model to use. Default: `gpt-image-1`. @@ -2153,14 +1989,8 @@ Compact a response - `"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`. @@ -2375,7 +2205,7 @@ Compact a response - `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) + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) - `name: string` @@ -2489,7 +2319,7 @@ Compact a response - `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) + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) - `name: string` @@ -2814,7 +2644,7 @@ Compact a response - `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](https://platform.openai.com/docs/guides/tools-web-search). + [web search tool](/docs/guides/tools-web-search). - `type: "web_search" or "web_search_2025_08_26"` @@ -2874,7 +2704,7 @@ Compact a response - `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](https://platform.openai.com/docs/guides/tools-remote-mcp). + (MCP) servers. [Learn more about MCP](/docs/guides/tools-remote-mcp). - `server_label: string` @@ -2926,7 +2756,7 @@ Compact a response 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). + about service connectors [here](/docs/guides/tools-remote-mcp#connectors). Currently supported `connector_id` values are: @@ -3118,19 +2948,8 @@ Compact a response - `background: optional "transparent" or "opaque" or "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`. + Background type for the generated image. One of `transparent`, + `opaque`, or `auto`. Default: `auto`. - `"transparent"` @@ -3159,13 +2978,13 @@ Compact a response Base64-encoded mask image. - - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-2" or 3 more` + - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` The image generation model to use. Default: `gpt-image-1`. - `string` - - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-2" or 3 more` + - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` The image generation model to use. Default: `gpt-image-1`. @@ -3173,14 +2992,8 @@ Compact a response - `"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`. @@ -3277,7 +3090,7 @@ Compact a response - `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) + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) - `name: string` @@ -3359,7 +3172,7 @@ Compact a response - `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) + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) - `name: string` @@ -3510,13 +3323,13 @@ Compact a response 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). + [managing context](/docs/guides/conversation-state). - `id: string` The unique identifier of the reasoning content. - - `summary: array of object { text, type }` + - `summary: array of SummaryTextContent` Reasoning summary content. @@ -3568,7 +3381,7 @@ Compact a response - `Compaction object { encrypted_content, type, id }` - A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). + A compaction item generated by the [`v1/responses/compact` API](/docs/api-reference/responses/compact). - `encrypted_content: string` @@ -4273,7 +4086,7 @@ Compact a response - `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). + An image input to the model. Learn about [image inputs](/docs/guides/vision). - `ResponseInputFile object { type, detail, file_data, 4 more }` @@ -4446,7 +4259,7 @@ Compact a response - `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](https://platform.openai.com/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](/docs/guides/conversation-state). Cannot be used in conjunction with `conversation`. - `prompt_cache_key: optional string` @@ -4454,7 +4267,7 @@ Compact a response - `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. + 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](/docs/guides/prompt-caching) for current details. - `mode: optional "implicit" or "explicit"` @@ -4508,23 +4321,47 @@ Compact a response - `"response.compaction"` - - `output: array of ResponseOutputItem` + - `output: array of Message or object { id, call_id, code, 2 more } or object { id, call_id, result, 2 more } or 25 more` - The compacted list of output items. This is a list of all user messages, followed by a single compaction item. + The compacted list of output items. - - `ResponseOutputMessage object { id, content, role, 3 more }` + - `Message object { id, content, role, 3 more }` - An output message from the model. + A message to or from the model. - `id: string` - The unique ID of the output message. + The unique ID of the message. - - `content: array of ResponseOutputText or ResponseOutputRefusal` + - `content: array of ResponseInputText or ResponseOutputText or TextContent or 6 more` - The content of the output message. + The content of the message + + - `ResponseInputText object { text, type, prompt_cache_breakpoint }` + + A text input to the model. + + - `text: string` + + The text input to the model. + + - `type: "input_text"` + + The type of the input item. Always `input_text`. + + - `"input_text"` + + - `prompt_cache_breakpoint: 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"` - - `ResponseOutputText object { annotations, text, type, logprobs }` + - `ResponseOutputText object { annotations, logprobs, text, type }` A text output from the model. @@ -4628,17 +4465,7 @@ Compact a response - `"file_path"` - - `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 }` + - `logprobs: array of object { token, bytes, logprob, top_logprobs }` - `token: string` @@ -4654,219 +4481,97 @@ Compact a response - `logprob: number` - - `ResponseOutputRefusal object { refusal, type }` + - `text: string` - A refusal from the model. + The text output from the model. - - `refusal: string` + - `type: "output_text"` - The refusal explanation from the model. + The type of the output text. Always `output_text`. - - `type: "refusal"` + - `"output_text"` - The type of the refusal. Always `refusal`. + - `TextContent object { text, type }` - - `"refusal"` + A text content. - - `role: "assistant"` + - `text: string` - The role of the output message. Always `assistant`. + - `type: "text"` - - `"assistant"` + - `"text"` - - `status: "in_progress" or "completed" or "incomplete"` + - `SummaryTextContent object { text, type }` - The status of the message input. One of `in_progress`, `completed`, or - `incomplete`. Populated when input items are returned via API. + A summary text from the model. - - `"in_progress"` + - `text: string` - - `"completed"` + A summary of the reasoning output from the model so far. - - `"incomplete"` + - `type: "summary_text"` - - `type: "message"` + The type of the object. Always `summary_text`. - The type of the output message. Always `message`. + - `"summary_text"` - - `"message"` - - - `phase: optional "commentary" or "final_answer"` - - 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. - - - `"commentary"` + - `ReasoningText object { text, type }` - - `"final_answer"` + Reasoning text from the model. - - `FileSearchCall object { id, queries, status, 2 more }` + - `text: string` - 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. + The reasoning text from the model. - - `id: string` + - `type: "reasoning_text"` - The unique ID of the file search tool call. + The type of the reasoning text. Always `reasoning_text`. - - `queries: array of string` + - `"reasoning_text"` - The queries used to search for files. + - `ResponseOutputRefusal object { refusal, type }` - - `status: "in_progress" or "searching" or "completed" or 2 more` + A refusal from the model. - The status of the file search tool call. One of `in_progress`, - `searching`, `incomplete` or `failed`, + - `refusal: string` - - `"in_progress"` + The refusal explanation from the model. - - `"searching"` + - `type: "refusal"` - - `"completed"` + The type of the refusal. Always `refusal`. - - `"incomplete"` + - `"refusal"` - - `"failed"` + - `ResponseInputImage object { detail, type, file_id, 2 more }` - - `type: "file_search_call"` + An image input to the model. Learn about [image inputs](/docs/guides/vision). - The type of the file search tool call. Always `file_search_call`. + - `detail: "low" or "high" or "auto" or "original"` - - `"file_search_call"` + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - - `results: optional array of object { attributes, file_id, filename, 2 more }` + - `"low"` - The results of the file search tool call. + - `"high"` - - `attributes: optional map[string or number or boolean]` + - `"auto"` - 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. + - `"original"` - - `string` + - `type: "input_image"` - - `number` + The type of the input item. Always `input_image`. - - `boolean` + - `"input_image"` - `file_id: optional string` - The unique ID of the file. - - - `filename: optional string` - - The name of the file. - - - `score: optional number` - - The relevance score of the file - a value between 0 and 1. - - - `text: optional string` - - The text that was retrieved from the file. - - - `FunctionCall object { arguments, call_id, name, 5 more }` - - A tool call to run a function. See the - [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. - - - `arguments: string` - - A JSON string of the arguments to pass to the function. - - - `call_id: string` - - The unique ID of the function tool call generated by the model. - - - `name: string` - - The name of the function to run. - - - `type: "function_call"` - - The type of the function tool call. Always `function_call`. - - - `"function_call"` - - - `id: optional string` - - 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. - - - `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. - - - `"in_progress"` - - - `"completed"` - - - `"incomplete"` - - - `FunctionCallOutput object { id, call_id, output, 4 more }` - - - `id: string` - - The unique ID of the function call tool output. - - - `call_id: string` - - The unique ID of the function tool call generated by the model. - - - `output: string or array of ResponseInputText or ResponseInputImage or ResponseInputFile` - - The output from the function call generated by your code. - Can be a string or an list of output content. - - - `StringOutput = string` - - A string of the output of the function call. - - - `OutputContentList = array of ResponseInputText or ResponseInputImage or ResponseInputFile` - - Text, image, or file output of the function call. - - - `ResponseInputText object { text, type, prompt_cache_breakpoint }` - - A text input to the model. - - - `text: string` - - The text input to the model. - - - `type: "input_text"` + The ID of the file to be sent to the model. - The type of the input item. Always `input_text`. + - `image_url: optional string` - - `"input_text"` + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - `prompt_cache_breakpoint: optional object { mode }` @@ -4878,13 +4583,13 @@ Compact a response - `"explicit"` - - `ResponseInputImage object { detail, type, file_id, 2 more }` + - `ComputerScreenshotContent object { detail, file_id, image_url, 2 more }` - An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). + A screenshot of a computer. - `detail: "low" or "high" or "auto" or "original"` - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + The detail level of the screenshot image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - `"low"` @@ -4894,19 +4599,19 @@ Compact a response - `"original"` - - `type: "input_image"` + - `file_id: string` - The type of the input item. Always `input_image`. + The identifier of an uploaded file that contains the screenshot. - - `"input_image"` + - `image_url: string` - - `file_id: optional string` + The URL of the screenshot image. - The ID of the file to be sent to the model. + - `type: "computer_screenshot"` - - `image_url: optional string` + Specifies the event type. For a computer screenshot, this property is always set to `computer_screenshot`. - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + - `"computer_screenshot"` - `prompt_cache_breakpoint: optional object { mode }` @@ -4964,180 +4669,189 @@ Compact a response - `"explicit"` - - `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. + - `role: "unknown" or "user" or "assistant" or 5 more` - - `"in_progress"` + The role of the message. One of `unknown`, `user`, `assistant`, `system`, `critic`, `discriminator`, `developer`, or `tool`. - - `"completed"` + - `"unknown"` - - `"incomplete"` + - `"user"` - - `type: "function_call_output"` + - `"assistant"` - The type of the function tool call output. Always `function_call_output`. + - `"system"` - - `"function_call_output"` + - `"critic"` - - `caller: optional object { type } or object { caller_id, type }` + - `"discriminator"` - The execution context that produced this tool call. + - `"developer"` - - `Direct object { type }` + - `"tool"` - - `type: "direct"` + - `status: "in_progress" or "completed" or "incomplete"` - The caller type. Always `direct`. + The status of item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. - - `"direct"` + - `"in_progress"` - - `Program object { caller_id, type }` + - `"completed"` - - `caller_id: string` + - `"incomplete"` - The call ID of the program item that produced this tool call. + - `type: "message"` - - `type: "program"` + The type of the message. Always set to `message`. - The caller type. Always `program`. + - `"message"` - - `"program"` + - `phase: optional "commentary" or "final_answer"` - - `created_by: optional 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 identifier of the actor that created the item. + - `"commentary"` - - `WebSearchCall object { id, action, status, type }` + - `"final_answer"` - 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. + - `Program object { id, call_id, code, 2 more }` - `id: string` - The unique ID of the web search tool call. + The unique ID of the program item. - - `action: object { type, queries, query, sources } or object { type, url } or object { pattern, type, url }` + - `call_id: 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 stable call ID of the program item. - - `Search object { type, queries, query, sources }` + - `code: string` - Action type "search" - Performs a web search query. + The JavaScript source executed by programmatic tool calling. - - `type: "search"` + - `fingerprint: string` - The action type. + Opaque program replay fingerprint that must be round-tripped. - - `"search"` + - `type: "program"` - - `queries: optional array of string` + The type of the item. Always `program`. - The search queries. + - `"program"` - - `query: optional string` + - `ProgramOutput object { id, call_id, result, 2 more }` - The search query. + - `id: string` - - `sources: optional array of object { type, url }` + The unique ID of the program output item. - The sources used in the search. + - `call_id: string` - - `type: "url"` + The call ID of the program item. - The type of source. Always `url`. + - `result: string` - - `"url"` + The result produced by the program item. - - `url: string` + - `status: "completed" or "incomplete"` - The URL of the source. + The terminal status of the program output item. - - `OpenPage object { type, url }` + - `"completed"` - Action type "open_page" - Opens a specific URL from search results. + - `"incomplete"` - - `type: "open_page"` + - `type: "program_output"` - The action type. + The type of the item. Always `program_output`. - - `"open_page"` + - `"program_output"` - - `url: optional string` + - `FunctionCall object { arguments, call_id, name, 5 more }` - The URL opened by the model. + A tool call to run a function. See the + [function calling guide](/docs/guides/function-calling) for more information. - - `FindInPage object { pattern, type, url }` + - `arguments: string` - Action type "find_in_page": Searches for a pattern within a loaded page. + A JSON string of the arguments to pass to the function. - - `pattern: string` + - `call_id: string` - The pattern or text to search for within the page. + The unique ID of the function tool call generated by the model. - - `type: "find_in_page"` + - `name: string` - The action type. + The name of the function to run. - - `"find_in_page"` + - `type: "function_call"` - - `url: string` + The type of the function tool call. Always `function_call`. - The URL of the page searched for the pattern. + - `"function_call"` - - `status: "in_progress" or "searching" or "completed" or "failed"` + - `id: optional string` - The status of the web search tool call. + The unique ID of the function tool call. - - `"in_progress"` + - `caller: optional object { type } or object { caller_id, type }` - - `"searching"` + The execution context that produced this tool call. - - `"completed"` + - `Direct object { type }` - - `"failed"` + - `type: "direct"` - - `type: "web_search_call"` + - `"direct"` - The type of the web search tool call. Always `web_search_call`. + - `Program object { caller_id, type }` - - `"web_search_call"` + - `caller_id: string` - - `ComputerCall object { id, call_id, pending_safety_checks, 4 more }` + The call ID of the program item that produced this tool call. - 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. + - `type: "program"` - - `id: string` + - `"program"` - The unique ID of the computer call. + - `namespace: optional string` - - `call_id: string` + The namespace of the function to run. - An identifier used when responding to the tool call with output. + - `status: optional "in_progress" or "completed" or "incomplete"` - - `pending_safety_checks: array of object { id, code, message }` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - The pending safety checks for the computer call. + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `ToolSearchCall object { id, arguments, call_id, 4 more }` - `id: string` - The ID of the pending safety check. + The unique ID of the tool search call item. - - `code: optional string` + - `arguments: unknown` - The type of the pending safety check. + Arguments used for the tool search call. - - `message: optional string` + - `call_id: string` - Details about the pending safety check. + The unique ID of the tool search call generated by the model. + + - `execution: "server" or "client"` + + Whether tool search was executed by the server or by the client. + + - `"server"` + + - `"client"` - `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. + The status of the tool search call item that was recorded. - `"in_progress"` @@ -5145,942 +4859,943 @@ Compact a response - `"incomplete"` - - `type: "computer_call"` + - `type: "tool_search_call"` - The type of the computer call. Always `computer_call`. + The type of the item. Always `tool_search_call`. - - `"computer_call"` + - `"tool_search_call"` - - `action: optional object { button, type, x, 2 more } or object { keys, type, x, y } or object { path, type, keys } or 6 more` + - `created_by: optional string` - A click action. + The identifier of the actor that created the item. - - `Click object { button, type, x, 2 more }` + - `ToolSearchOutput object { id, call_id, execution, 4 more }` - A click action. + - `id: string` - - `button: "left" or "right" or "wheel" or 2 more` + The unique ID of the tool search output item. - Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. + - `call_id: string` - - `"left"` + The unique ID of the tool search call generated by the model. - - `"right"` + - `execution: "server" or "client"` - - `"wheel"` + Whether tool search was executed by the server or by the client. - - `"back"` + - `"server"` - - `"forward"` + - `"client"` - - `type: "click"` + - `status: "in_progress" or "completed" or "incomplete"` - Specifies the event type. For a click action, this property is always `click`. + The status of the tool search output item that was recorded. - - `"click"` + - `"in_progress"` - - `x: number` + - `"completed"` - The x-coordinate where the click occurred. + - `"incomplete"` - - `y: number` + - `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 y-coordinate where the click occurred. + The loaded tool definitions returned by tool search. - - `keys: optional array of string` + - `Function object { name, parameters, strict, 5 more }` - The keys being held while clicking. + 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). - - `DoubleClick object { keys, type, x, y }` + - `name: string` - A double click action. + The name of the function to call. - - `keys: array of string` + - `parameters: map[unknown]` - The keys being held while double-clicking. + A JSON schema object describing the parameters of the function. - - `type: "double_click"` + - `strict: boolean` - Specifies the event type. For a double click action, this property is always set to `double_click`. + Whether strict parameter validation is enforced for this function tool. - - `"double_click"` + - `type: "function"` - - `x: number` + The type of the function tool. Always `function`. - The x-coordinate where the double click occurred. + - `"function"` - - `y: number` + - `allowed_callers: optional array of "direct" or "programmatic"` - The y-coordinate where the double click occurred. + The tool invocation context(s). - - `Drag object { path, type, keys }` + - `"direct"` - A drag action. + - `"programmatic"` - - `path: array of object { x, y }` + - `defer_loading: optional boolean` - An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg + Whether this function is deferred and loaded via tool search. - ``` - [ - { x: 100, y: 200 }, - { x: 200, y: 300 } - ] - ``` + - `description: optional string` - - `x: number` + A description of the function. Used by the model to determine whether or not to call the function. - The x-coordinate. + - `output_schema: optional map[unknown]` - - `y: number` + A JSON schema object describing the JSON value encoded in string outputs for this function. - The y-coordinate. + - `FileSearch object { type, vector_store_ids, filters, 2 more }` - - `type: "drag"` + 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). - Specifies the event type. For a drag action, this property is always set to `drag`. + - `type: "file_search"` - - `"drag"` + The type of the file search tool. Always `file_search`. - - `keys: optional array of string` + - `"file_search"` - The keys being held while dragging the mouse. + - `vector_store_ids: array of string` - - `Keypress object { keys, type }` + The IDs of the vector stores to search. - A collection of keypresses the model would like to perform. + - `filters: optional ComparisonFilter or CompoundFilter` - - `keys: array of string` + A filter to apply. - The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. + - `ComparisonFilter object { key, type, value }` - - `type: "keypress"` + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - Specifies the event type. For a keypress action, this property is always set to `keypress`. + - `key: string` - - `"keypress"` + The key to compare against the value. - - `Move object { type, x, y, keys }` + - `type: "eq" or "ne" or "gt" or 5 more` - A mouse move action. + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - - `type: "move"` + - `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 - Specifies the event type. For a move action, this property is always set to `move`. + - `"eq"` - - `"move"` + - `"ne"` - - `x: number` + - `"gt"` - The x-coordinate to move to. + - `"gte"` - - `y: number` + - `"lt"` - The y-coordinate to move to. + - `"lte"` - - `keys: optional array of string` + - `"in"` - The keys being held while moving the mouse. + - `"nin"` - - `Screenshot object { type }` + - `value: string or number or boolean or array of string or number` - A screenshot action. + The value to compare against the attribute key; supports string, number, or boolean types. - - `type: "screenshot"` + - `string` - Specifies the event type. For a screenshot action, this property is always set to `screenshot`. + - `number` - - `"screenshot"` + - `boolean` - - `Scroll object { scroll_x, scroll_y, type, 3 more }` + - `array of string or number` - A scroll action. + - `string` - - `scroll_x: number` + - `number` - The horizontal scroll distance. + - `CompoundFilter object { filters, type }` - - `scroll_y: number` + Combine multiple filters using `and` or `or`. - The vertical scroll distance. + - `filters: array of ComparisonFilter or unknown` - - `type: "scroll"` + Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. - Specifies the event type. For a scroll action, this property is always set to `scroll`. + - `ComparisonFilter object { key, type, value }` - - `"scroll"` + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - - `x: number` + - `unknown` - The x-coordinate where the scroll occurred. + - `type: "and" or "or"` - - `y: number` + Type of operation: `and` or `or`. - The y-coordinate where the scroll occurred. + - `"and"` - - `keys: optional array of string` + - `"or"` - The keys being held while scrolling. + - `max_num_results: optional number` - - `Type object { text, type }` + The maximum number of results to return. This number should be between 1 and 50 inclusive. - An action to type in text. + - `ranking_options: optional object { hybrid_search, ranker, score_threshold }` - - `text: string` + Ranking options for search. - The text to type. + - `hybrid_search: optional object { embedding_weight, text_weight }` - - `type: "type"` + Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. - Specifies the event type. For a type action, this property is always set to `type`. + - `embedding_weight: number` - - `"type"` + The weight of the embedding in the reciprocal ranking fusion. - - `Wait object { type }` + - `text_weight: number` - A wait action. + The weight of the text in the reciprocal ranking fusion. - - `type: "wait"` + - `ranker: optional "auto" or "default-2024-11-15"` - Specifies the event type. For a wait action, this property is always set to `wait`. + The ranker to use for the file search. - - `"wait"` + - `"auto"` - - `actions: optional ComputerActionList` + - `"default-2024-11-15"` - Flattened batched actions for `computer_use`. Each action includes an - `type` discriminator and action-specific fields. + - `score_threshold: optional number` - - `Click object { button, type, x, 2 more }` + 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. - A click action. + - `Computer object { type }` - - `button: "left" or "right" or "wheel" or 2 more` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. + - `type: "computer"` - - `"left"` + The type of the computer tool. Always `computer`. - - `"right"` + - `"computer"` - - `"wheel"` + - `ComputerUsePreview object { display_height, display_width, environment, type }` - - `"back"` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `"forward"` + - `display_height: number` - - `type: "click"` + The height of the computer display. - Specifies the event type. For a click action, this property is always `click`. + - `display_width: number` - - `"click"` + The width of the computer display. - - `x: number` + - `environment: "windows" or "mac" or "linux" or 2 more` - The x-coordinate where the click occurred. + The type of computer environment to control. - - `y: number` + - `"windows"` - The y-coordinate where the click occurred. + - `"mac"` - - `keys: optional array of string` + - `"linux"` - The keys being held while clicking. + - `"ubuntu"` - - `DoubleClick object { keys, type, x, y }` + - `"browser"` - A double click action. + - `type: "computer_use_preview"` - - `keys: array of string` + The type of the computer use tool. Always `computer_use_preview`. - The keys being held while double-clicking. + - `"computer_use_preview"` - - `type: "double_click"` + - `WebSearch object { type, filters, search_context_size, user_location }` - Specifies the event type. For a double click action, this property is always set to `double_click`. + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](/docs/guides/tools-web-search). - - `"double_click"` + - `type: "web_search" or "web_search_2025_08_26"` - - `x: number` + The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. - The x-coordinate where the double click occurred. + - `"web_search"` - - `y: number` + - `"web_search_2025_08_26"` - The y-coordinate where the double click occurred. + - `filters: optional object { allowed_domains }` - - `Drag object { path, type, keys }` + Filters for the search. - A drag action. + - `allowed_domains: optional array of string` - - `path: array of object { x, y }` + Allowed domains for the search. If not provided, all domains are allowed. + Subdomains of the provided domains are allowed as well. - An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg + Example: `["pubmed.ncbi.nlm.nih.gov"]` - ``` - [ - { x: 100, y: 200 }, - { x: 200, y: 300 } - ] - ``` + - `search_context_size: optional "low" or "medium" or "high"` - - `x: number` + 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 x-coordinate. + - `"low"` - - `y: number` + - `"medium"` - The y-coordinate. + - `"high"` - - `type: "drag"` + - `user_location: optional object { city, country, region, 2 more }` - Specifies the event type. For a drag action, this property is always set to `drag`. + The approximate location of the user. - - `"drag"` + - `city: optional string` - - `keys: optional array of string` + Free text input for the city of the user, e.g. `San Francisco`. - The keys being held while dragging the mouse. + - `country: optional string` - - `Keypress object { keys, type }` + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - A collection of keypresses the model would like to perform. + - `region: optional string` - - `keys: array of string` + Free text input for the region of the user, e.g. `California`. - The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. + - `timezone: optional string` - - `type: "keypress"` + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - Specifies the event type. For a keypress action, this property is always set to `keypress`. + - `type: optional "approximate"` - - `"keypress"` + The type of location approximation. Always `approximate`. - - `Move object { type, x, y, keys }` + - `"approximate"` - A mouse move action. + - `Mcp object { server_label, type, allowed_callers, 9 more }` - - `type: "move"` + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](/docs/guides/tools-remote-mcp). - Specifies the event type. For a move action, this property is always set to `move`. + - `server_label: string` - - `"move"` + A label for this MCP server, used to identify it in tool calls. - - `x: number` + - `type: "mcp"` - The x-coordinate to move to. + The type of the MCP tool. Always `mcp`. - - `y: number` + - `"mcp"` - The y-coordinate to move to. + - `allowed_callers: optional array of "direct" or "programmatic"` - - `keys: optional array of string` + The tool invocation context(s). - The keys being held while moving the mouse. + - `"direct"` - - `Screenshot object { type }` + - `"programmatic"` - A screenshot action. + - `allowed_tools: optional array of string or object { read_only, tool_names }` - - `type: "screenshot"` + List of allowed tool names or a filter object. - Specifies the event type. For a screenshot action, this property is always set to `screenshot`. + - `McpAllowedTools = array of string` - - `"screenshot"` + A string array of allowed tool names - - `Scroll object { scroll_x, scroll_y, type, 3 more }` + - `McpToolFilter object { read_only, tool_names }` - A scroll action. + A filter object to specify which tools are allowed. - - `scroll_x: number` + - `read_only: optional boolean` - The horizontal scroll distance. + 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. - - `scroll_y: number` + - `tool_names: optional array of string` - The vertical scroll distance. + List of allowed tool names. - - `type: "scroll"` + - `authorization: optional string` - Specifies the event type. For a scroll action, this property is always set to `scroll`. + 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. - - `"scroll"` + - `connector_id: optional "connector_dropbox" or "connector_gmail" or "connector_googlecalendar" or 5 more` - - `x: number` + 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). - The x-coordinate where the scroll occurred. + Currently supported `connector_id` values are: - - `y: number` + - 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 y-coordinate where the scroll occurred. + - `"connector_dropbox"` - - `keys: optional array of string` + - `"connector_gmail"` - The keys being held while scrolling. + - `"connector_googlecalendar"` - - `Type object { text, type }` + - `"connector_googledrive"` - An action to type in text. + - `"connector_microsoftteams"` - - `text: string` + - `"connector_outlookcalendar"` - The text to type. + - `"connector_outlookemail"` - - `type: "type"` + - `"connector_sharepoint"` - Specifies the event type. For a type action, this property is always set to `type`. + - `defer_loading: optional boolean` - - `"type"` + Whether this MCP tool is deferred and discovered via tool search. - - `Wait object { type }` + - `headers: optional map[string]` - A wait action. + Optional HTTP headers to send to the MCP server. Use for authentication + or other purposes. - - `type: "wait"` + - `require_approval: optional object { always, never } or "always" or "never"` - Specifies the event type. For a wait action, this property is always set to `wait`. + Specify which of the MCP server's tools require approval. - - `"wait"` + - `McpToolApprovalFilter object { always, never }` - - `ComputerCallOutput object { id, call_id, output, 4 more }` + Specify which of the MCP server's tools require approval. Can be + `always`, `never`, or a filter object associated with tools + that require approval. - - `id: string` + - `always: optional object { read_only, tool_names }` - The unique ID of the computer call tool output. + A filter object to specify which tools are allowed. - - `call_id: string` + - `read_only: optional boolean` - The ID of the computer tool call that produced the output. + 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. - - `output: ResponseComputerToolCallOutputScreenshot` + - `tool_names: optional array of string` - A computer screenshot image used with the computer use tool. + List of allowed tool names. - - `type: "computer_screenshot"` + - `never: optional object { read_only, tool_names }` - Specifies the event type. For a computer screenshot, this property is - always set to `computer_screenshot`. + A filter object to specify which tools are allowed. - - `"computer_screenshot"` + - `read_only: optional boolean` - - `file_id: 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. - The identifier of an uploaded file that contains the screenshot. + - `tool_names: optional array of string` - - `image_url: optional string` + List of allowed tool names. - The URL of the screenshot image. + - `McpToolApprovalSetting = "always" or "never"` - - `status: "completed" or "incomplete" or "failed" or "in_progress"` + 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. - The status of the message input. One of `in_progress`, `completed`, or - `incomplete`. Populated when input items are returned via API. + - `"always"` - - `"completed"` + - `"never"` - - `"incomplete"` + - `server_description: optional string` - - `"failed"` + Optional description of the MCP server, used to provide more context. - - `"in_progress"` + - `server_url: optional string` - - `type: "computer_call_output"` + The URL for the MCP server. One of `server_url`, `connector_id`, or + `tunnel_id` must be provided. - The type of the computer tool call output. Always `computer_call_output`. + - `tunnel_id: optional string` - - `"computer_call_output"` + 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. - - `acknowledged_safety_checks: optional array of object { id, code, message }` + - `CodeInterpreter object { container, type, allowed_callers }` - The safety checks reported by the API that have been acknowledged by the - developer. + A tool that runs Python code to help generate a response to a prompt. - - `id: string` + - `container: string or object { type, file_ids, memory_limit, network_policy }` - The ID of the pending safety check. + 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. - - `code: optional string` + - `string` - The type of the pending safety check. + The container ID. - - `message: optional string` + - `CodeInterpreterToolAuto object { type, file_ids, memory_limit, network_policy }` - Details about the pending safety check. + Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. - - `created_by: optional string` + - `type: "auto"` - The identifier of the actor that created the item. + Always `auto`. - - `Reasoning object { id, summary, type, 3 more }` + - `"auto"` - 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). + - `file_ids: optional array of string` - - `id: string` + An optional list of uploaded files to make available to your code. - The unique identifier of the reasoning content. + - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` - - `summary: array of object { text, type }` + The memory limit for the code interpreter container. - Reasoning summary content. + - `"1g"` - - `text: string` + - `"4g"` - A summary of the reasoning output from the model so far. + - `"16g"` - - `type: "summary_text"` + - `"64g"` - The type of the object. Always `summary_text`. + - `network_policy: optional ContainerNetworkPolicyDisabled or ContainerNetworkPolicyAllowlist` - - `"summary_text"` + Network access policy for the container. - - `type: "reasoning"` + - `ContainerNetworkPolicyDisabled object { type }` - The type of the object. Always `reasoning`. + - `type: "disabled"` - - `"reasoning"` + Disable outbound network access. Always `disabled`. - - `content: optional array of object { text, type }` + - `"disabled"` - Reasoning text content. + - `ContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` - - `text: string` + - `allowed_domains: array of string` - The reasoning text from the model. + A list of allowed domains when type is `allowlist`. - - `type: "reasoning_text"` + - `type: "allowlist"` - The type of the reasoning text. Always `reasoning_text`. + Allow outbound network access only to specified domains. Always `allowlist`. - - `"reasoning_text"` + - `"allowlist"` - - `encrypted_content: optional string` + - `domain_secrets: optional array of ContainerNetworkPolicyDomainSecret` - The encrypted content of the reasoning item - populated when a response is - generated with `reasoning.encrypted_content` in the `include` parameter. + Optional domain-scoped secrets for allowlisted domains. - - `status: optional "in_progress" or "completed" or "incomplete"` + - `domain: string` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + The domain associated with the secret. - - `"in_progress"` + - `name: string` - - `"completed"` + The name of the secret to inject for the domain. - - `"incomplete"` + - `value: string` - - `Program object { id, call_id, code, 2 more }` + The secret value to inject for the domain. - - `id: string` + - `type: "code_interpreter"` - The unique ID of the program item. + The type of the code interpreter tool. Always `code_interpreter`. - - `call_id: string` + - `"code_interpreter"` - The stable call ID of the program item. + - `allowed_callers: optional array of "direct" or "programmatic"` - - `code: string` + The tool invocation context(s). - The JavaScript source executed by programmatic tool calling. + - `"direct"` - - `fingerprint: string` + - `"programmatic"` - Opaque program replay fingerprint that must be round-tripped. + - `ProgrammaticToolCalling object { type }` - - `type: "program"` + - `type: "programmatic_tool_calling"` - The type of the item. Always `program`. + The type of the tool. Always `programmatic_tool_calling`. - - `"program"` + - `"programmatic_tool_calling"` - - `ProgramOutput object { id, call_id, result, 2 more }` + - `ImageGeneration object { type, action, background, 9 more }` - - `id: string` + A tool that generates images using the GPT image models. - The unique ID of the program output item. + - `type: "image_generation"` - - `call_id: string` + The type of the image generation tool. Always `image_generation`. - The call ID of the program item. + - `"image_generation"` - - `result: string` + - `action: optional "generate" or "edit" or "auto"` - The result produced by the program item. + Whether to generate a new image or edit an existing image. Default: `auto`. - - `status: "completed" or "incomplete"` + - `"generate"` - The terminal status of the program output item. + - `"edit"` - - `"completed"` + - `"auto"` - - `"incomplete"` + - `background: optional "transparent" or "opaque" or "auto"` - - `type: "program_output"` + Background type for the generated image. One of `transparent`, + `opaque`, or `auto`. Default: `auto`. - The type of the item. Always `program_output`. + - `"transparent"` - - `"program_output"` + - `"opaque"` - - `ToolSearchCall object { id, arguments, call_id, 4 more }` + - `"auto"` - - `id: string` + - `input_fidelity: optional "high" or "low"` - The unique ID of the tool search call item. + 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`. - - `arguments: unknown` + - `"high"` - Arguments used for the tool search call. + - `"low"` - - `call_id: string` + - `input_image_mask: optional object { file_id, image_url }` - The unique ID of the tool search call generated by the model. + Optional mask for inpainting. Contains `image_url` + (string, optional) and `file_id` (string, optional). - - `execution: "server" or "client"` + - `file_id: optional string` - Whether tool search was executed by the server or by the client. + File ID for the mask image. - - `"server"` + - `image_url: optional string` - - `"client"` + Base64-encoded mask image. - - `status: "in_progress" or "completed" or "incomplete"` + - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` - The status of the tool search call item that was recorded. + The image generation model to use. Default: `gpt-image-1`. - - `"in_progress"` + - `string` - - `"completed"` + - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` - - `"incomplete"` + The image generation model to use. Default: `gpt-image-1`. - - `type: "tool_search_call"` + - `"gpt-image-1"` - The type of the item. Always `tool_search_call`. + - `"gpt-image-1-mini"` - - `"tool_search_call"` + - `"gpt-image-1.5"` - - `created_by: optional string` + - `moderation: optional "auto" or "low"` - The identifier of the actor that created the item. + Moderation level for the generated image. Default: `auto`. - - `ToolSearchOutput object { id, call_id, execution, 4 more }` + - `"auto"` - - `id: string` + - `"low"` - The unique ID of the tool search output item. + - `output_compression: optional number` - - `call_id: string` + Compression level for the output image. Default: 100. - The unique ID of the tool search call generated by the model. + - `output_format: optional "png" or "webp" or "jpeg"` - - `execution: "server" or "client"` + The output format of the generated image. One of `png`, `webp`, or + `jpeg`. Default: `png`. - Whether tool search was executed by the server or by the client. + - `"png"` - - `"server"` + - `"webp"` - - `"client"` + - `"jpeg"` - - `status: "in_progress" or "completed" or "incomplete"` + - `partial_images: optional number` - The status of the tool search output item that was recorded. + Number of partial images to generate in streaming mode, from 0 (default value) to 3. - - `"in_progress"` + - `quality: optional "low" or "medium" or "high" or "auto"` - - `"completed"` + The quality of the generated image. One of `low`, `medium`, `high`, + or `auto`. Default: `auto`. - - `"incomplete"` + - `"low"` - - `tools: array of object { name, parameters, strict, 5 more } or object { type, vector_store_ids, filters, 2 more } or object { type } or 13 more` + - `"medium"` - The loaded tool definitions returned by tool search. + - `"high"` - - `Function object { name, parameters, strict, 5 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). + - `size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or "auto"` - - `name: string` + 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 name of the function to call. + - `string` - - `parameters: map[unknown]` + - `"1024x1024" or "1024x1536" or "1536x1024" or "auto"` - A JSON schema object describing the parameters of the function. + 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`. - - `strict: boolean` + - `"1024x1024"` - Whether strict parameter validation is enforced for this function tool. + - `"1024x1536"` - - `type: "function"` + - `"1536x1024"` - The type of the function tool. Always `function`. + - `"auto"` - - `"function"` + - `LocalShell object { type }` - - `allowed_callers: optional array of "direct" or "programmatic"` + A tool that allows the model to execute shell commands in a local environment. - The tool invocation context(s). + - `type: "local_shell"` - - `"direct"` + The type of the local shell tool. Always `local_shell`. - - `"programmatic"` + - `"local_shell"` - - `defer_loading: optional boolean` + - `Shell object { type, allowed_callers, environment }` - Whether this function is deferred and loaded via tool search. + A tool that allows the model to execute shell commands. - - `description: optional string` + - `type: "shell"` - A description of the function. Used by the model to determine whether or not to call the function. + The type of the shell tool. Always `shell`. - - `output_schema: optional map[unknown]` + - `"shell"` - A JSON schema object describing the JSON value encoded in string outputs for this function. + - `allowed_callers: optional array of "direct" or "programmatic"` - - `FileSearch object { type, vector_store_ids, filters, 2 more }` + The tool invocation context(s). - 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). + - `"direct"` - - `type: "file_search"` + - `"programmatic"` - The type of the file search tool. Always `file_search`. + - `environment: optional ContainerAuto or LocalEnvironment or ContainerReference` - - `"file_search"` + - `ContainerAuto object { type, file_ids, memory_limit, 2 more }` - - `vector_store_ids: array of string` + - `type: "container_auto"` - The IDs of the vector stores to search. + Automatically creates a container for this request - - `filters: optional ComparisonFilter or CompoundFilter` + - `"container_auto"` - A filter to apply. + - `file_ids: optional array of string` - - `ComparisonFilter object { key, type, value }` + An optional list of uploaded files to make available to your code. - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` - - `key: string` + The memory limit for the container. - The key to compare against the value. + - `"1g"` - - `type: "eq" or "ne" or "gt" or 5 more` + - `"4g"` - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + - `"16g"` - - `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 + - `"64g"` - - `"eq"` + - `network_policy: optional ContainerNetworkPolicyDisabled or ContainerNetworkPolicyAllowlist` - - `"ne"` + Network access policy for the container. - - `"gt"` + - `ContainerNetworkPolicyDisabled object { type }` - - `"gte"` + - `ContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` - - `"lt"` + - `skills: optional array of SkillReference or InlineSkill` - - `"lte"` + An optional list of skills referenced by id or inline data. - - `"in"` + - `SkillReference object { skill_id, type, version }` - - `"nin"` + - `skill_id: string` - - `value: string or number or boolean or array of string or number` + The ID of the referenced skill. - The value to compare against the attribute key; supports string, number, or boolean types. + - `type: "skill_reference"` - - `string` + References a skill created with the /v1/skills endpoint. - - `number` + - `"skill_reference"` - - `boolean` + - `version: optional string` - - `array of string or number` + Optional skill version. Use a positive integer or 'latest'. Omit for default. - - `string` + - `InlineSkill object { description, name, source, type }` - - `number` + - `description: string` - - `CompoundFilter object { filters, type }` + The description of the skill. - Combine multiple filters using `and` or `or`. + - `name: string` - - `filters: array of ComparisonFilter or unknown` + The name of the skill. - Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. + - `source: InlineSkillSource` - - `ComparisonFilter object { key, type, value }` + Inline skill payload - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + - `data: string` - - `unknown` + Base64-encoded skill zip bundle. - - `type: "and" or "or"` + - `media_type: "application/zip"` - Type of operation: `and` or `or`. + The media type of the inline skill payload. Must be `application/zip`. - - `"and"` + - `"application/zip"` - - `"or"` + - `type: "base64"` - - `max_num_results: optional number` + The type of the inline skill source. Must be `base64`. - The maximum number of results to return. This number should be between 1 and 50 inclusive. + - `"base64"` - - `ranking_options: optional object { hybrid_search, ranker, score_threshold }` + - `type: "inline"` - Ranking options for search. + Defines an inline skill for this request. - - `hybrid_search: optional object { embedding_weight, text_weight }` + - `"inline"` - Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. + - `LocalEnvironment object { type, skills }` - - `embedding_weight: number` + - `type: "local"` - The weight of the embedding in the reciprocal ranking fusion. + Use a local computer environment. - - `text_weight: number` + - `"local"` - The weight of the text in the reciprocal ranking fusion. + - `skills: optional array of LocalSkill` - - `ranker: optional "auto" or "default-2024-11-15"` + An optional list of skills. - The ranker to use for the file search. + - `description: string` - - `"auto"` + The description of the skill. - - `"default-2024-11-15"` + - `name: string` - - `score_threshold: optional number` + The name of the skill. - 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. + - `path: string` - - `Computer object { type }` + The path to the directory containing the skill. - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `ContainerReference object { container_id, type }` - - `type: "computer"` + - `container_id: string` - The type of the computer tool. Always `computer`. + The ID of the referenced container. - - `"computer"` + - `type: "container_reference"` - - `ComputerUsePreview object { display_height, display_width, environment, type }` + References a container created with the /v1/containers endpoint - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `"container_reference"` - - `display_height: number` + - `Custom object { name, type, allowed_callers, 3 more }` - The height of the computer display. + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) - - `display_width: number` + - `name: string` - The width of the computer display. + The name of the custom tool, used to identify it in tool calls. - - `environment: "windows" or "mac" or "linux" or 2 more` + - `type: "custom"` - The type of computer environment to control. + The type of the custom tool. Always `custom`. - - `"windows"` + - `"custom"` - - `"mac"` + - `allowed_callers: optional array of "direct" or "programmatic"` - - `"linux"` + The tool invocation context(s). - - `"ubuntu"` + - `"direct"` - - `"browser"` + - `"programmatic"` - - `type: "computer_use_preview"` + - `defer_loading: optional boolean` - The type of the computer use tool. Always `computer_use_preview`. + Whether this tool should be deferred and discovered via tool search. - - `"computer_use_preview"` + - `description: optional string` - - `WebSearch object { type, filters, search_context_size, user_location }` + Optional description of the custom tool, used to provide more context. - 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). + - `format: optional CustomToolInputFormat` - - `type: "web_search" or "web_search_2025_08_26"` + The input format for the custom tool. Default is unconstrained text. - The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. + - `Text object { type }` - - `"web_search"` + Unconstrained free-form text. - - `"web_search_2025_08_26"` + - `type: "text"` - - `filters: optional object { allowed_domains }` + Unconstrained text format. Always `text`. - Filters for the search. + - `"text"` - - `allowed_domains: optional array of string` + - `Grammar object { definition, syntax, type }` - Allowed domains for the search. If not provided, all domains are allowed. - Subdomains of the provided domains are allowed as well. + A grammar defined by the user. - Example: `["pubmed.ncbi.nlm.nih.gov"]` + - `definition: string` - - `search_context_size: optional "low" or "medium" or "high"` + The grammar definition. - 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. + - `syntax: "lark" or "regex"` - - `"low"` - - - `"medium"` - - - `"high"` - - - `user_location: optional object { city, country, region, 2 more }` - - The approximate location of the user. - - - `city: optional string` + The syntax of the grammar definition. One of `lark` or `regex`. - Free text input for the city of the user, e.g. `San Francisco`. + - `"lark"` - - `country: optional string` + - `"regex"` - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + - `type: "grammar"` - - `region: optional string` + Grammar format. Always `grammar`. - Free text input for the region of the user, e.g. `California`. + - `"grammar"` - - `timezone: optional string` + - `Namespace object { description, name, tools, type }` - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + Groups function/custom tools under a shared namespace. - - `type: optional "approximate"` + - `description: string` - The type of location approximation. Always `approximate`. + A description of the namespace shown to the model. - - `"approximate"` + - `name: string` - - `Mcp object { server_label, type, allowed_callers, 9 more }` + The namespace name used in tool calls (for example, `crm`). - 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). + - `tools: array of object { name, type, allowed_callers, 5 more } or object { name, type, allowed_callers, 3 more }` - - `server_label: string` + The function/custom tools available inside this namespace. - A label for this MCP server, used to identify it in tool calls. + - `Function object { name, type, allowed_callers, 5 more }` - - `type: "mcp"` + - `name: string` - The type of the MCP tool. Always `mcp`. + - `type: "function"` - - `"mcp"` + - `"function"` - `allowed_callers: optional array of "direct" or "programmatic"` @@ -6090,626 +5805,610 @@ Compact a response - `"programmatic"` - - `allowed_tools: optional array of string or object { read_only, tool_names }` + - `defer_loading: optional boolean` - List of allowed tool names or a filter object. + Whether this function should be deferred and discovered via tool search. - - `McpAllowedTools = array of string` + - `description: optional string` - A string array of allowed tool names + - `output_schema: optional map[unknown]` - - `McpToolFilter object { read_only, tool_names }` + A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. - A filter object to specify which tools are allowed. + - `parameters: optional unknown` - - `read_only: optional boolean` + - `strict: optional boolean` - 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. + 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. - - `tool_names: optional array of string` + - `Custom object { name, type, allowed_callers, 3 more }` - List of allowed tool names. + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) - - `authorization: optional string` + - `name: string` - 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 name of the custom tool, used to identify it in tool calls. - - `connector_id: optional "connector_dropbox" or "connector_gmail" or "connector_googlecalendar" or 5 more` + - `type: "custom"` - 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 type of the custom tool. Always `custom`. - Currently supported `connector_id` values are: + - `"custom"` - - 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` + - `allowed_callers: optional array of "direct" or "programmatic"` - - `"connector_dropbox"` + The tool invocation context(s). - - `"connector_gmail"` + - `"direct"` - - `"connector_googlecalendar"` + - `"programmatic"` - - `"connector_googledrive"` + - `defer_loading: optional boolean` - - `"connector_microsoftteams"` + Whether this tool should be deferred and discovered via tool search. - - `"connector_outlookcalendar"` + - `description: optional string` - - `"connector_outlookemail"` + Optional description of the custom tool, used to provide more context. - - `"connector_sharepoint"` + - `format: optional CustomToolInputFormat` - - `defer_loading: optional boolean` + The input format for the custom tool. Default is unconstrained text. - Whether this MCP tool is deferred and discovered via tool search. + - `type: "namespace"` - - `headers: optional map[string]` + The type of the tool. Always `namespace`. - Optional HTTP headers to send to the MCP server. Use for authentication - or other purposes. + - `"namespace"` - - `require_approval: optional object { always, never } or "always" or "never"` + - `ToolSearch object { type, description, execution, parameters }` - Specify which of the MCP server's tools require approval. + Hosted or BYOT tool search configuration for deferred tools. - - `McpToolApprovalFilter object { always, never }` + - `type: "tool_search"` - Specify which of the MCP server's tools require approval. Can be - `always`, `never`, or a filter object associated with tools - that require approval. + The type of the tool. Always `tool_search`. - - `always: optional object { read_only, tool_names }` + - `"tool_search"` - A filter object to specify which tools are allowed. + - `description: optional string` - - `read_only: optional boolean` + Description shown to the model for a client-executed tool search tool. - 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. + - `execution: optional "server" or "client"` - - `tool_names: optional array of string` + Whether tool search is executed by the server or by the client. - List of allowed tool names. + - `"server"` - - `never: optional object { read_only, tool_names }` + - `"client"` - A filter object to specify which tools are allowed. + - `parameters: optional unknown` - - `read_only: optional boolean` + Parameter schema for a client-executed tool search tool. - 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. + - `WebSearchPreview object { type, search_content_types, search_context_size, user_location }` - - `tool_names: optional array of string` + 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). - List of allowed tool names. + - `type: "web_search_preview" or "web_search_preview_2025_03_11"` - - `McpToolApprovalSetting = "always" or "never"` + The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. - 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. + - `"web_search_preview"` - - `"always"` + - `"web_search_preview_2025_03_11"` - - `"never"` + - `search_content_types: optional array of "text" or "image"` - - `server_description: optional string` + - `"text"` - Optional description of the MCP server, used to provide more context. + - `"image"` - - `server_url: optional string` + - `search_context_size: optional "low" or "medium" or "high"` - The URL for the MCP server. One of `server_url`, `connector_id`, or - `tunnel_id` must be provided. + 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. - - `tunnel_id: optional string` + - `"low"` - 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. + - `"medium"` - - `CodeInterpreter object { container, type, allowed_callers }` + - `"high"` - A tool that runs Python code to help generate a response to a prompt. + - `user_location: optional object { type, city, country, 2 more }` - - `container: string or object { type, file_ids, memory_limit, network_policy }` + The user's location. - 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: "approximate"` - - `string` + The type of location approximation. Always `approximate`. - The container ID. + - `"approximate"` - - `CodeInterpreterToolAuto object { type, file_ids, memory_limit, network_policy }` + - `city: optional string` - Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. + Free text input for the city of the user, e.g. `San Francisco`. - - `type: "auto"` + - `country: optional string` - Always `auto`. + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - - `"auto"` + - `region: optional string` - - `file_ids: optional array of string` + Free text input for the region of the user, e.g. `California`. - An optional list of uploaded files to make available to your code. + - `timezone: optional string` - - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - The memory limit for the code interpreter container. + - `ApplyPatch object { type, allowed_callers }` - - `"1g"` + Allows the assistant to create, delete, or update files using unified diffs. - - `"4g"` + - `type: "apply_patch"` - - `"16g"` + The type of the tool. Always `apply_patch`. - - `"64g"` + - `"apply_patch"` - - `network_policy: optional ContainerNetworkPolicyDisabled or ContainerNetworkPolicyAllowlist` + - `allowed_callers: optional array of "direct" or "programmatic"` - Network access policy for the container. + The tool invocation context(s). - - `ContainerNetworkPolicyDisabled object { type }` + - `"direct"` - - `type: "disabled"` + - `"programmatic"` - Disable outbound network access. Always `disabled`. + - `type: "tool_search_output"` - - `"disabled"` + The type of the item. Always `tool_search_output`. - - `ContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` + - `"tool_search_output"` - - `allowed_domains: array of string` + - `created_by: optional string` - A list of allowed domains when type is `allowlist`. + The identifier of the actor that created the item. - - `type: "allowlist"` + - `AdditionalTools object { id, role, tools, type }` - Allow outbound network access only to specified domains. Always `allowlist`. + - `id: string` - - `"allowlist"` + The unique ID of the additional tools item. - - `domain_secrets: optional array of ContainerNetworkPolicyDomainSecret` + - `role: "unknown" or "user" or "assistant" or 5 more` - Optional domain-scoped secrets for allowlisted domains. + The role that provided the additional tools. - - `domain: string` + - `"unknown"` - The domain associated with the secret. + - `"user"` - - `name: string` + - `"assistant"` - The name of the secret to inject for the domain. + - `"system"` - - `value: string` + - `"critic"` - The secret value to inject for the domain. + - `"discriminator"` - - `type: "code_interpreter"` - - The type of the code interpreter tool. Always `code_interpreter`. + - `"developer"` - - `"code_interpreter"` + - `"tool"` - - `allowed_callers: optional array of "direct" or "programmatic"` + - `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 tool invocation context(s). + The additional tool definitions made available at this item. - - `"direct"` + - `Function object { name, parameters, strict, 5 more }` - - `"programmatic"` + 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). - - `ProgrammaticToolCalling object { type }` + - `name: string` - - `type: "programmatic_tool_calling"` + The name of the function to call. - The type of the tool. Always `programmatic_tool_calling`. + - `parameters: map[unknown]` - - `"programmatic_tool_calling"` + A JSON schema object describing the parameters of the function. - - `ImageGeneration object { type, action, background, 9 more }` + - `strict: boolean` - A tool that generates images using the GPT image models. + Whether strict parameter validation is enforced for this function tool. - - `type: "image_generation"` + - `type: "function"` - The type of the image generation tool. Always `image_generation`. + The type of the function tool. Always `function`. - - `"image_generation"` + - `"function"` - - `action: optional "generate" or "edit" or "auto"` + - `allowed_callers: optional array of "direct" or "programmatic"` - Whether to generate a new image or edit an existing image. Default: `auto`. + The tool invocation context(s). - - `"generate"` + - `"direct"` - - `"edit"` + - `"programmatic"` - - `"auto"` + - `defer_loading: optional boolean` - - `background: optional "transparent" or "opaque" or "auto"` + Whether this function is deferred and loaded via tool search. - 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. + - `description: 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. + A description of the function. Used by the model to determine whether or not to call the function. - If `transparent`, the output format needs to support transparency, - so it should be set to either `png` (default value) or `webp`. + - `output_schema: optional map[unknown]` - - `"transparent"` + A JSON schema object describing the JSON value encoded in string outputs for this function. - - `"opaque"` + - `FileSearch object { type, vector_store_ids, filters, 2 more }` - - `"auto"` + 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). - - `input_fidelity: optional "high" or "low"` + - `type: "file_search"` - 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 type of the file search tool. Always `file_search`. - - `"high"` + - `"file_search"` - - `"low"` + - `vector_store_ids: array of string` - - `input_image_mask: optional object { file_id, image_url }` + The IDs of the vector stores to search. - Optional mask for inpainting. Contains `image_url` - (string, optional) and `file_id` (string, optional). + - `filters: optional ComparisonFilter or CompoundFilter` - - `file_id: optional string` + A filter to apply. - File ID for the mask image. + - `ComparisonFilter object { key, type, value }` - - `image_url: optional string` + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - Base64-encoded mask image. + - `CompoundFilter object { filters, type }` - - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-2" or 3 more` + Combine multiple filters using `and` or `or`. - The image generation model to use. Default: `gpt-image-1`. + - `max_num_results: optional number` - - `string` + The maximum number of results to return. This number should be between 1 and 50 inclusive. - - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-2" or 3 more` + - `ranking_options: optional object { hybrid_search, ranker, score_threshold }` - The image generation model to use. Default: `gpt-image-1`. + Ranking options for search. - - `"gpt-image-1"` + - `hybrid_search: optional object { embedding_weight, text_weight }` - - `"gpt-image-1-mini"` + Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. - - `"gpt-image-2"` + - `embedding_weight: number` - - `"gpt-image-2-2026-04-21"` + The weight of the embedding in the reciprocal ranking fusion. - - `"gpt-image-1.5"` + - `text_weight: number` - - `"chatgpt-image-latest"` + The weight of the text in the reciprocal ranking fusion. - - `moderation: optional "auto" or "low"` + - `ranker: optional "auto" or "default-2024-11-15"` - Moderation level for the generated image. Default: `auto`. + The ranker to use for the file search. - `"auto"` - - `"low"` + - `"default-2024-11-15"` - - `output_compression: optional number` + - `score_threshold: optional number` - Compression level for the output image. Default: 100. + 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. - - `output_format: optional "png" or "webp" or "jpeg"` + - `Computer object { type }` - The output format of the generated image. One of `png`, `webp`, or - `jpeg`. Default: `png`. + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `"png"` + - `type: "computer"` - - `"webp"` + The type of the computer tool. Always `computer`. - - `"jpeg"` + - `"computer"` - - `partial_images: optional number` + - `ComputerUsePreview object { display_height, display_width, environment, type }` - Number of partial images to generate in streaming mode, from 0 (default value) to 3. + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `quality: optional "low" or "medium" or "high" or "auto"` + - `display_height: number` - The quality of the generated image. One of `low`, `medium`, `high`, - or `auto`. Default: `auto`. + The height of the computer display. - - `"low"` + - `display_width: number` - - `"medium"` + The width of the computer display. - - `"high"` + - `environment: "windows" or "mac" or "linux" or 2 more` - - `"auto"` + The type of computer environment to control. - - `size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or "auto"` + - `"windows"` - 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`. + - `"mac"` - - `string` + - `"linux"` - - `"1024x1024" or "1024x1536" or "1536x1024" or "auto"` + - `"ubuntu"` - 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`. + - `"browser"` - - `"1024x1024"` + - `type: "computer_use_preview"` - - `"1024x1536"` + The type of the computer use tool. Always `computer_use_preview`. - - `"1536x1024"` + - `"computer_use_preview"` - - `"auto"` + - `WebSearch object { type, filters, search_context_size, user_location }` - - `LocalShell object { type }` + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](/docs/guides/tools-web-search). - A tool that allows the model to execute shell commands in a local environment. + - `type: "web_search" or "web_search_2025_08_26"` - - `type: "local_shell"` + The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. - The type of the local shell tool. Always `local_shell`. + - `"web_search"` - - `"local_shell"` + - `"web_search_2025_08_26"` - - `Shell object { type, allowed_callers, environment }` + - `filters: optional object { allowed_domains }` - A tool that allows the model to execute shell commands. + Filters for the search. - - `type: "shell"` + - `allowed_domains: optional array of string` - The type of the shell tool. Always `shell`. + Allowed domains for the search. If not provided, all domains are allowed. + Subdomains of the provided domains are allowed as well. - - `"shell"` + Example: `["pubmed.ncbi.nlm.nih.gov"]` - - `allowed_callers: optional array of "direct" or "programmatic"` + - `search_context_size: optional "low" or "medium" or "high"` - The tool invocation context(s). + 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. - - `"direct"` + - `"low"` - - `"programmatic"` + - `"medium"` - - `environment: optional ContainerAuto or LocalEnvironment or ContainerReference` + - `"high"` - - `ContainerAuto object { type, file_ids, memory_limit, 2 more }` + - `user_location: optional object { city, country, region, 2 more }` - - `type: "container_auto"` + The approximate location of the user. - Automatically creates a container for this request + - `city: optional string` - - `"container_auto"` + Free text input for the city of the user, e.g. `San Francisco`. - - `file_ids: optional array of string` + - `country: optional string` - An optional list of uploaded files to make available to your code. + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` + - `region: optional string` - The memory limit for the container. + Free text input for the region of the user, e.g. `California`. - - `"1g"` + - `timezone: optional string` - - `"4g"` + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - - `"16g"` + - `type: optional "approximate"` - - `"64g"` + The type of location approximation. Always `approximate`. - - `network_policy: optional ContainerNetworkPolicyDisabled or ContainerNetworkPolicyAllowlist` + - `"approximate"` - Network access policy for the container. + - `Mcp object { server_label, type, allowed_callers, 9 more }` - - `ContainerNetworkPolicyDisabled object { type }` + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](/docs/guides/tools-remote-mcp). - - `ContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` + - `server_label: string` - - `skills: optional array of SkillReference or InlineSkill` + A label for this MCP server, used to identify it in tool calls. - An optional list of skills referenced by id or inline data. + - `type: "mcp"` - - `SkillReference object { skill_id, type, version }` + The type of the MCP tool. Always `mcp`. - - `skill_id: string` + - `"mcp"` - The ID of the referenced skill. + - `allowed_callers: optional array of "direct" or "programmatic"` - - `type: "skill_reference"` + The tool invocation context(s). - References a skill created with the /v1/skills endpoint. + - `"direct"` - - `"skill_reference"` + - `"programmatic"` - - `version: optional string` + - `allowed_tools: optional array of string or object { read_only, tool_names }` - Optional skill version. Use a positive integer or 'latest'. Omit for default. + List of allowed tool names or a filter object. - - `InlineSkill object { description, name, source, type }` + - `McpAllowedTools = array of string` - - `description: string` + A string array of allowed tool names - The description of the skill. + - `McpToolFilter object { read_only, tool_names }` - - `name: string` + A filter object to specify which tools are allowed. - The name of the skill. + - `read_only: optional boolean` - - `source: InlineSkillSource` + 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. - Inline skill payload + - `tool_names: optional array of string` - - `data: string` + List of allowed tool names. - Base64-encoded skill zip bundle. + - `authorization: optional string` - - `media_type: "application/zip"` + 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 media type of the inline skill payload. Must be `application/zip`. + - `connector_id: optional "connector_dropbox" or "connector_gmail" or "connector_googlecalendar" or 5 more` - - `"application/zip"` - - - `type: "base64"` - - The type of the inline skill source. Must be `base64`. - - - `"base64"` + 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: "inline"` + Currently supported `connector_id` values are: - Defines an inline skill for this request. + - 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` - - `"inline"` + - `"connector_dropbox"` - - `LocalEnvironment object { type, skills }` + - `"connector_gmail"` - - `type: "local"` + - `"connector_googlecalendar"` - Use a local computer environment. + - `"connector_googledrive"` - - `"local"` + - `"connector_microsoftteams"` - - `skills: optional array of LocalSkill` + - `"connector_outlookcalendar"` - An optional list of skills. + - `"connector_outlookemail"` - - `description: string` + - `"connector_sharepoint"` - The description of the skill. + - `defer_loading: optional boolean` - - `name: string` + Whether this MCP tool is deferred and discovered via tool search. - The name of the skill. + - `headers: optional map[string]` - - `path: string` + Optional HTTP headers to send to the MCP server. Use for authentication + or other purposes. - The path to the directory containing the skill. + - `require_approval: optional object { always, never } or "always" or "never"` - - `ContainerReference object { container_id, type }` + Specify which of the MCP server's tools require approval. - - `container_id: string` + - `McpToolApprovalFilter object { always, never }` - The ID of the referenced container. + 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: "container_reference"` + - `always: optional object { read_only, tool_names }` - References a container created with the /v1/containers endpoint + A filter object to specify which tools are allowed. - - `"container_reference"` + - `read_only: optional boolean` - - `Custom object { name, type, allowed_callers, 3 more }` + 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. - 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) + - `tool_names: optional array of string` - - `name: string` + List of allowed tool names. - The name of the custom tool, used to identify it in tool calls. + - `never: optional object { read_only, tool_names }` - - `type: "custom"` + A filter object to specify which tools are allowed. - The type of the custom tool. Always `custom`. + - `read_only: optional boolean` - - `"custom"` + 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. - - `allowed_callers: optional array of "direct" or "programmatic"` + - `tool_names: optional array of string` - The tool invocation context(s). + List of allowed tool names. - - `"direct"` + - `McpToolApprovalSetting = "always" or "never"` - - `"programmatic"` + 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. - - `Text object { type }` + - `tunnel_id: optional string` - Unconstrained free-form text. + 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. - - `type: "text"` + - `CodeInterpreter object { container, type, allowed_callers }` - Unconstrained text format. Always `text`. + A tool that runs Python code to help generate a response to a prompt. - - `"text"` + - `container: string or object { type, file_ids, memory_limit, network_policy }` - - `Grammar object { definition, syntax, type }` + 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. - A grammar defined by the user. + - `string` - - `definition: string` + The container ID. - The grammar definition. + - `CodeInterpreterToolAuto object { type, file_ids, memory_limit, network_policy }` - - `syntax: "lark" or "regex"` + Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. - The syntax of the grammar definition. One of `lark` or `regex`. + - `type: "auto"` - - `"lark"` + Always `auto`. - - `"regex"` + - `"auto"` - - `type: "grammar"` + - `file_ids: optional array of string` - Grammar format. Always `grammar`. + An optional list of uploaded files to make available to your code. - - `"grammar"` + - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` - - `Namespace object { description, name, tools, type }` + The memory limit for the code interpreter container. - Groups function/custom tools under a shared namespace. + - `"1g"` - - `description: string` + - `"4g"` - A description of the namespace shown to the model. + - `"16g"` - - `name: string` + - `"64g"` - The namespace name used in tool calls (for example, `crm`). + - `network_policy: optional ContainerNetworkPolicyDisabled or ContainerNetworkPolicyAllowlist` - - `tools: array of object { name, type, allowed_callers, 5 more } or object { name, type, allowed_callers, 3 more }` + Network access policy for the container. - The function/custom tools available inside this namespace. + - `ContainerNetworkPolicyDisabled object { type }` - - `Function object { name, type, allowed_callers, 5 more }` + - `ContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` - - `name: string` + - `type: "code_interpreter"` - - `type: "function"` + The type of the code interpreter tool. Always `code_interpreter`. - - `"function"` + - `"code_interpreter"` - `allowed_callers: optional array of "direct" or "programmatic"` @@ -6719,109 +6418,113 @@ Compact a response - `"programmatic"` - - `defer_loading: optional boolean` + - `ProgrammaticToolCalling object { type }` - Whether this function should be deferred and discovered via tool search. + - `type: "programmatic_tool_calling"` - - `description: optional string` + The type of the tool. Always `programmatic_tool_calling`. - - `output_schema: optional map[unknown]` + - `"programmatic_tool_calling"` - A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. + - `ImageGeneration object { type, action, background, 9 more }` - - `parameters: optional unknown` + A tool that generates images using the GPT image models. - - `strict: optional boolean` + - `type: "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. + The type of the image generation tool. Always `image_generation`. - - `Custom object { name, type, allowed_callers, 3 more }` + - `"image_generation"` - 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) + - `action: optional "generate" or "edit" or "auto"` - - `name: string` + Whether to generate a new image or edit an existing image. Default: `auto`. - The name of the custom tool, used to identify it in tool calls. + - `"generate"` - - `type: "custom"` + - `"edit"` - The type of the custom tool. Always `custom`. + - `"auto"` - - `"custom"` + - `background: optional "transparent" or "opaque" or "auto"` - - `allowed_callers: optional array of "direct" or "programmatic"` + Background type for the generated image. One of `transparent`, + `opaque`, or `auto`. Default: `auto`. - The tool invocation context(s). + - `"transparent"` - - `"direct"` + - `"opaque"` - - `"programmatic"` + - `"auto"` - - `defer_loading: optional boolean` + - `input_fidelity: optional "high" or "low"` - Whether this tool should be deferred and discovered via tool search. + 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`. - - `description: optional string` + - `"high"` - Optional description of the custom tool, used to provide more context. + - `"low"` - - `format: optional CustomToolInputFormat` + - `input_image_mask: optional object { file_id, image_url }` - The input format for the custom tool. Default is unconstrained text. + Optional mask for inpainting. Contains `image_url` + (string, optional) and `file_id` (string, optional). - - `type: "namespace"` + - `file_id: optional string` - The type of the tool. Always `namespace`. + File ID for the mask image. - - `"namespace"` + - `image_url: optional string` - - `ToolSearch object { type, description, execution, parameters }` + Base64-encoded mask image. - Hosted or BYOT tool search configuration for deferred tools. + - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` - - `type: "tool_search"` + The image generation model to use. Default: `gpt-image-1`. - The type of the tool. Always `tool_search`. + - `string` - - `"tool_search"` + - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` - - `description: optional string` + The image generation model to use. Default: `gpt-image-1`. - Description shown to the model for a client-executed tool search tool. + - `"gpt-image-1"` - - `execution: optional "server" or "client"` + - `"gpt-image-1-mini"` - Whether tool search is executed by the server or by the client. + - `"gpt-image-1.5"` - - `"server"` + - `moderation: optional "auto" or "low"` - - `"client"` + Moderation level for the generated image. Default: `auto`. - - `parameters: optional unknown` + - `"auto"` - Parameter schema for a client-executed tool search tool. + - `"low"` - - `WebSearchPreview object { type, search_content_types, search_context_size, user_location }` + - `output_compression: optional number` - 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). + Compression level for the output image. Default: 100. - - `type: "web_search_preview" or "web_search_preview_2025_03_11"` + - `output_format: optional "png" or "webp" or "jpeg"` - The type of the web search tool. One of `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`. - - `"web_search_preview"` + - `"png"` - - `"web_search_preview_2025_03_11"` + - `"webp"` - - `search_content_types: optional array of "text" or "image"` + - `"jpeg"` - - `"text"` + - `partial_images: optional number` - - `"image"` + Number of partial images to generate in streaming mode, from 0 (default value) to 3. - - `search_context_size: optional "low" or "medium" or "high"` + - `quality: optional "low" or "medium" or "high" or "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. + The quality of the generated image. One of `low`, `medium`, `high`, + or `auto`. Default: `auto`. - `"low"` @@ -6829,41 +6532,45 @@ Compact a response - `"high"` - - `user_location: optional object { type, city, country, 2 more }` + - `"auto"` - The user's location. + - `size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or "auto"` - - `type: "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`. - The type of location approximation. Always `approximate`. + - `string` - - `"approximate"` + - `"1024x1024" or "1024x1536" or "1536x1024" or "auto"` - - `city: optional string` + 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`. - Free text input for the city of the user, e.g. `San Francisco`. + - `"1024x1024"` - - `country: optional string` + - `"1024x1536"` - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + - `"1536x1024"` - - `region: optional string` + - `"auto"` - Free text input for the region of the user, e.g. `California`. + - `LocalShell object { type }` - - `timezone: optional string` + A tool that allows the model to execute shell commands in a local environment. - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + - `type: "local_shell"` - - `ApplyPatch object { type, allowed_callers }` + The type of the local shell tool. Always `local_shell`. - Allows the assistant to create, delete, or update files using unified diffs. + - `"local_shell"` - - `type: "apply_patch"` + - `Shell object { type, allowed_callers, environment }` - The type of the tool. Always `apply_patch`. + A tool that allows the model to execute shell commands. - - `"apply_patch"` + - `type: "shell"` + + The type of the shell tool. Always `shell`. + + - `"shell"` - `allowed_callers: optional array of "direct" or "programmatic"` @@ -6873,66 +6580,70 @@ Compact a response - `"programmatic"` - - `type: "tool_search_output"` + - `environment: optional ContainerAuto or LocalEnvironment or ContainerReference` - The type of the item. Always `tool_search_output`. + - `ContainerAuto object { type, file_ids, memory_limit, 2 more }` - - `"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, allowed_callers, 3 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"` + - `allowed_callers: optional array of "direct" or "programmatic"` - - `"assistant"` + The tool invocation context(s). - - `"system"` + - `"direct"` - - `"critic"` + - `"programmatic"` - - `"discriminator"` + - `defer_loading: optional boolean` - - `"developer"` + Whether this tool should be deferred and discovered via tool search. - - `"tool"` + - `description: optional string` - - `tools: array of object { name, parameters, strict, 5 more } or object { type, vector_store_ids, filters, 2 more } or object { type } or 13 more` + Optional description of the custom tool, used to provide more context. - The additional tool definitions made available at this item. + - `format: optional CustomToolInputFormat` - - `Function object { name, parameters, strict, 5 more }` + The input format for the custom tool. Default is unconstrained text. - 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). + - `Namespace object { description, name, tools, type }` + + Groups function/custom tools under a shared namespace. + + - `description: string` + + A description of the namespace shown to the model. - `name: string` - The name of the function to call. + The namespace name used in tool calls (for example, `crm`). - - `parameters: map[unknown]` + - `tools: array of object { name, type, allowed_callers, 5 more } or object { name, type, allowed_callers, 3 more }` - A JSON schema object describing the parameters of the function. + The function/custom tools available inside this namespace. - - `strict: boolean` + - `Function object { name, type, allowed_callers, 5 more }` - Whether strict parameter validation is enforced for this function tool. + - `name: string` - `type: "function"` - The type of the function tool. Always `function`. - - `"function"` - `allowed_callers: optional array of "direct" or "programmatic"` @@ -6945,139 +6656,103 @@ Compact a response - `defer_loading: optional boolean` - Whether this function is deferred and loaded via tool search. + Whether this function should be deferred and discovered via tool search. - `description: optional string` - 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). - - - `type: "file_search"` - - The type of the file search tool. Always `file_search`. - - - `"file_search"` - - - `vector_store_ids: array of string` - - The IDs of the vector stores to search. - - - `filters: optional ComparisonFilter or CompoundFilter` - - A filter to apply. - - - `ComparisonFilter object { key, type, value }` - - A filter used to compare a specified attribute key to a given value using a defined comparison operation. - - - `CompoundFilter object { filters, type }` - - Combine multiple filters using `and` or `or`. - - - `max_num_results: optional number` - - The maximum number of results to return. This number should be between 1 and 50 inclusive. - - - `ranking_options: optional object { hybrid_search, ranker, score_threshold }` + A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. - Ranking options for search. + - `parameters: optional unknown` - - `hybrid_search: optional object { embedding_weight, text_weight }` + - `strict: optional boolean` - Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. + 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. - - `embedding_weight: number` + - `Custom object { name, type, allowed_callers, 3 more }` - The weight of the embedding in the reciprocal ranking fusion. + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) - - `text_weight: number` + - `name: string` - The weight of the text in the reciprocal ranking fusion. + The name of the custom tool, used to identify it in tool calls. - - `ranker: optional "auto" or "default-2024-11-15"` + - `type: "custom"` - The ranker to use for the file search. + The type of the custom tool. Always `custom`. - - `"auto"` + - `"custom"` - - `"default-2024-11-15"` + - `allowed_callers: optional array of "direct" or "programmatic"` - - `score_threshold: optional number` + The tool invocation context(s). - 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. + - `"direct"` - - `Computer object { type }` + - `"programmatic"` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `defer_loading: optional boolean` - - `type: "computer"` + Whether this tool should be deferred and discovered via tool search. - The type of the computer tool. Always `computer`. + - `description: optional string` - - `"computer"` + Optional description of the custom tool, used to provide more context. - - `ComputerUsePreview object { display_height, display_width, environment, type }` + - `format: optional CustomToolInputFormat` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + The input format for the custom tool. Default is unconstrained text. - - `display_height: number` + - `type: "namespace"` - The height of the computer display. + The type of the tool. Always `namespace`. - - `display_width: number` + - `"namespace"` - The width of the computer display. + - `ToolSearch object { type, description, execution, parameters }` - - `environment: "windows" or "mac" or "linux" or 2 more` + Hosted or BYOT tool search configuration for deferred tools. - The type of computer environment to control. + - `type: "tool_search"` - - `"windows"` + The type of the tool. Always `tool_search`. - - `"mac"` + - `"tool_search"` - - `"linux"` + - `description: optional string` - - `"ubuntu"` + Description shown to the model for a client-executed tool search tool. - - `"browser"` + - `execution: optional "server" or "client"` - - `type: "computer_use_preview"` + Whether tool search is executed by the server or by the client. - The type of the computer use tool. Always `computer_use_preview`. + - `"server"` - - `"computer_use_preview"` + - `"client"` - - `WebSearch object { type, filters, search_context_size, user_location }` + - `parameters: optional unknown` - 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). + Parameter schema for a client-executed tool search tool. - - `type: "web_search" or "web_search_2025_08_26"` + - `WebSearchPreview object { type, search_content_types, search_context_size, user_location }` - The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. + 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). - - `"web_search"` + - `type: "web_search_preview" or "web_search_preview_2025_03_11"` - - `"web_search_2025_08_26"` + The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. - - `filters: optional object { allowed_domains }` + - `"web_search_preview"` - Filters for the search. + - `"web_search_preview_2025_03_11"` - - `allowed_domains: optional array of string` + - `search_content_types: optional array of "text" or "image"` - Allowed domains for the search. If not provided, all domains are allowed. - Subdomains of the provided domains are allowed as well. + - `"text"` - Example: `["pubmed.ncbi.nlm.nih.gov"]` + - `"image"` - `search_context_size: optional "low" or "medium" or "high"` @@ -7089,9 +6764,15 @@ Compact a response - `"high"` - - `user_location: optional object { city, country, region, 2 more }` + - `user_location: optional object { type, city, country, 2 more }` - The approximate location of the user. + The user's location. + + - `type: "approximate"` + + The type of location approximation. Always `approximate`. + + - `"approximate"` - `city: optional string` @@ -7109,645 +6790,716 @@ Compact a response The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - - `type: optional "approximate"` + - `ApplyPatch object { type, allowed_callers }` - The type of location approximation. Always `approximate`. + Allows the assistant to create, delete, or update files using unified diffs. - - `"approximate"` + - `type: "apply_patch"` - - `Mcp object { server_label, type, allowed_callers, 9 more }` + The type of the tool. Always `apply_patch`. - 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). + - `"apply_patch"` - - `server_label: string` + - `allowed_callers: optional array of "direct" or "programmatic"` - A label for this MCP server, used to identify it in tool calls. + The tool invocation context(s). - - `type: "mcp"` + - `"direct"` - The type of the MCP tool. Always `mcp`. + - `"programmatic"` - - `"mcp"` + - `type: "additional_tools"` - - `allowed_callers: optional array of "direct" or "programmatic"` + The type of the item. Always `additional_tools`. - The tool invocation context(s). + - `"additional_tools"` + + - `FunctionCallOutput object { call_id, output, type, 3 more }` + + The output of a function tool call. + + - `call_id: string` + + The unique ID of the function tool call generated by the model. + + - `output: string or array of ResponseInputText or ResponseInputImage or ResponseInputFile` + + The output from the function call generated by your code. + Can be a string or an list of output content. + + - `StringOutput = string` + + A string of the output of the function call. + + - `OutputContentList = array of ResponseInputText or ResponseInputImage or ResponseInputFile` + + Text, image, or file output of the function call. + + - `ResponseInputText object { text, type, prompt_cache_breakpoint }` + + A text input to the model. + + - `ResponseInputImage object { detail, type, file_id, 2 more }` + + An image input to the model. Learn about [image inputs](/docs/guides/vision). + + - `ResponseInputFile object { type, detail, file_data, 4 more }` + + A file input to the model. + + - `type: "function_call_output"` + + The type of the function tool call output. Always `function_call_output`. + + - `"function_call_output"` + + - `id: optional string` + + 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"` - - `"programmatic"` + - `Program object { caller_id, type }` - - `allowed_tools: optional array of string or object { read_only, tool_names }` + - `caller_id: string` - List of allowed tool names or a filter object. + The call ID of the program item that produced this tool call. - - `McpAllowedTools = array of string` + - `type: "program"` - A string array of allowed tool names + The caller type. Always `program`. - - `McpToolFilter object { read_only, tool_names }` + - `"program"` - A filter object to specify which tools are allowed. + - `status: optional "in_progress" or "completed" or "incomplete"` - - `read_only: optional boolean` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - 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. + - `"in_progress"` - - `tool_names: optional array of string` + - `"completed"` - List of allowed tool names. + - `"incomplete"` - - `authorization: optional string` + - `FileSearchCall object { id, queries, status, 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 a file search tool call. See the + [file search guide](/docs/guides/tools-file-search) for more information. - - `connector_id: optional "connector_dropbox" or "connector_gmail" or "connector_googlecalendar" or 5 more` + - `id: 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 unique ID of the file search tool call. - Currently supported `connector_id` values are: + - `queries: array of 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` + The queries used to search for files. - - `"connector_dropbox"` + - `status: "in_progress" or "searching" or "completed" or 2 more` - - `"connector_gmail"` + The status of the file search tool call. One of `in_progress`, + `searching`, `incomplete` or `failed`, - - `"connector_googlecalendar"` + - `"in_progress"` - - `"connector_googledrive"` + - `"searching"` - - `"connector_microsoftteams"` + - `"completed"` - - `"connector_outlookcalendar"` + - `"incomplete"` - - `"connector_outlookemail"` + - `"failed"` - - `"connector_sharepoint"` + - `type: "file_search_call"` - - `defer_loading: optional boolean` + The type of the file search tool call. Always `file_search_call`. - Whether this MCP tool is deferred and discovered via tool search. + - `"file_search_call"` - - `headers: optional map[string]` + - `results: optional array of object { attributes, file_id, filename, 2 more }` - Optional HTTP headers to send to the MCP server. Use for authentication - or other purposes. + The results of the file search tool call. - - `require_approval: optional object { always, never } or "always" or "never"` + - `attributes: optional map[string or number or boolean]` - Specify which of the MCP server's tools require approval. + 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. - - `McpToolApprovalFilter object { always, never }` + - `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. + - `number` - - `always: optional object { read_only, tool_names }` + - `boolean` - A filter object to specify which tools are allowed. + - `file_id: optional string` - - `read_only: optional boolean` + The unique ID of the file. - 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. + - `filename: optional string` - - `tool_names: optional array of string` + The name of the file. - List of allowed tool names. + - `score: optional number` - - `never: optional object { read_only, tool_names }` + The relevance score of the file - a value between 0 and 1. - A filter object to specify which tools are allowed. + - `text: optional string` - - `read_only: optional boolean` + The text that was retrieved from the file. - 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. + - `WebSearchCall object { id, action, status, type }` - - `tool_names: optional array of string` + The results of a web search tool call. See the + [web search guide](/docs/guides/tools-web-search) for more information. - List of allowed tool names. + - `id: string` - - `McpToolApprovalSetting = "always" or "never"` + The unique ID of the web search tool call. - 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. + - `action: object { type, queries, query, sources } or object { type, url } or object { pattern, type, url }` - - `"always"` + 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). - - `"never"` + - `Search object { type, queries, query, sources }` - - `server_description: optional string` + Action type "search" - Performs a web search query. - Optional description of the MCP server, used to provide more context. + - `type: "search"` - - `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. + - `"search"` - - `tunnel_id: optional string` + - `queries: optional array of 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 search queries. - - `CodeInterpreter object { container, type, allowed_callers }` + - `query: optional string` - A tool that runs Python code to help generate a response to a prompt. + The search query. - - `container: string or object { type, file_ids, memory_limit, network_policy }` + - `sources: optional array of object { type, url }` - 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 sources used in the search. - - `string` + - `type: "url"` - The container ID. + The type of source. Always `url`. - - `CodeInterpreterToolAuto object { type, file_ids, memory_limit, network_policy }` + - `"url"` - 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 source. - Always `auto`. + - `OpenPage object { type, url }` - - `"auto"` + Action type "open_page" - Opens a specific URL from search results. - - `file_ids: optional array of string` + - `type: "open_page"` - An optional list of uploaded files to make available to your code. + The action type. - - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` + - `"open_page"` - The memory limit for the code interpreter container. + - `url: optional string` - - `"1g"` + The URL opened by the model. - - `"4g"` + - `FindInPage object { pattern, type, url }` - - `"16g"` + Action type "find_in_page": Searches for a pattern within a loaded page. - - `"64g"` + - `pattern: string` - - `network_policy: optional ContainerNetworkPolicyDisabled or ContainerNetworkPolicyAllowlist` + The pattern or text to search for within the page. - Network access policy for the container. + - `type: "find_in_page"` - - `ContainerNetworkPolicyDisabled object { type }` + The action type. - - `ContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` + - `"find_in_page"` - - `type: "code_interpreter"` + - `url: string` - The type of the code interpreter tool. Always `code_interpreter`. + The URL of the page searched for the pattern. - - `"code_interpreter"` + - `status: "in_progress" or "searching" or "completed" or "failed"` - - `allowed_callers: optional array of "direct" or "programmatic"` + The status of the web search tool call. - The tool invocation context(s). + - `"in_progress"` - - `"direct"` + - `"searching"` - - `"programmatic"` + - `"completed"` - - `ProgrammaticToolCalling object { type }` + - `"failed"` - - `type: "programmatic_tool_calling"` + - `type: "web_search_call"` - The type of the tool. Always `programmatic_tool_calling`. + The type of the web search tool call. Always `web_search_call`. - - `"programmatic_tool_calling"` + - `"web_search_call"` - - `ImageGeneration object { type, action, background, 9 more }` + - `ImageGenerationCall object { id, result, status, type }` - A tool that generates images using the GPT image models. + An image generation request made by the model. - - `type: "image_generation"` + - `id: string` - The type of the image generation tool. Always `image_generation`. + The unique ID of the image generation call. - - `"image_generation"` + - `result: string` - - `action: optional "generate" or "edit" or "auto"` + The generated image encoded in base64. - Whether to generate a new image or edit an existing image. Default: `auto`. + - `status: "in_progress" or "completed" or "generating" or "failed"` - - `"generate"` + The status of the image generation call. - - `"edit"` + - `"in_progress"` - - `"auto"` + - `"completed"` - - `background: optional "transparent" or "opaque" or "auto"` + - `"generating"` - 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. + - `"failed"` - `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. + - `type: "image_generation_call"` - If `transparent`, the output format needs to support transparency, - so it should be set to either `png` (default value) or `webp`. + The type of the image generation call. Always `image_generation_call`. - - `"transparent"` + - `"image_generation_call"` - - `"opaque"` + - `ComputerCall object { id, call_id, pending_safety_checks, 4 more }` - - `"auto"` + A tool call to a computer use tool. See the + [computer use guide](/docs/guides/tools-computer-use) for more information. - - `input_fidelity: optional "high" or "low"` + - `id: 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 unique ID of the computer call. - - `"high"` + - `call_id: string` - - `"low"` + An identifier used when responding to the tool call with output. - - `input_image_mask: optional object { file_id, image_url }` + - `pending_safety_checks: array of object { id, code, message }` - Optional mask for inpainting. Contains `image_url` - (string, optional) and `file_id` (string, optional). + The pending safety checks for the computer call. - - `file_id: optional string` + - `id: string` - File ID for the mask image. + The ID of the pending safety check. - - `image_url: optional string` + - `code: optional string` - Base64-encoded mask image. + The type of the pending safety check. - - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-2" or 3 more` + - `message: optional string` - The image generation model to use. Default: `gpt-image-1`. + Details about the pending safety check. - - `string` + - `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"` - - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-2" or 3 more` + - `type: "computer_call"` + + The type of the computer call. Always `computer_call`. + + - `"computer_call"` + + - `action: optional ComputerAction` + + A click action. + + - `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"` - The image generation model to use. Default: `gpt-image-1`. + - `"back"` - - `"gpt-image-1"` + - `"forward"` - - `"gpt-image-1-mini"` + - `type: "click"` - - `"gpt-image-2"` + Specifies the event type. For a click action, this property is always `click`. - - `"gpt-image-2-2026-04-21"` + - `"click"` - - `"gpt-image-1.5"` + - `x: number` - - `"chatgpt-image-latest"` + The x-coordinate where the click occurred. - - `moderation: optional "auto" or "low"` + - `y: number` - Moderation level for the generated image. Default: `auto`. + The y-coordinate where the click occurred. - - `"auto"` + - `keys: optional array of string` - - `"low"` + The keys being held while clicking. - - `output_compression: optional number` + - `DoubleClick object { keys, type, x, y }` - Compression level for the output image. Default: 100. + A double click action. - - `output_format: optional "png" or "webp" or "jpeg"` + - `keys: array of string` - The output format of the generated image. One of `png`, `webp`, or - `jpeg`. Default: `png`. + The keys being held while double-clicking. - - `"png"` + - `type: "double_click"` - - `"webp"` + Specifies the event type. For a double click action, this property is always set to `double_click`. - - `"jpeg"` + - `"double_click"` - - `partial_images: optional number` + - `x: number` - Number of partial images to generate in streaming mode, from 0 (default value) to 3. + The x-coordinate where the double click occurred. - - `quality: optional "low" or "medium" or "high" or "auto"` + - `y: number` - The quality of the generated image. One of `low`, `medium`, `high`, - or `auto`. Default: `auto`. + The y-coordinate where the double click occurred. - - `"low"` + - `Drag object { path, type, keys }` - - `"medium"` + A drag action. - - `"high"` + - `path: array of object { x, y }` - - `"auto"` + An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg - - `size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or "auto"` + ``` + [ + { x: 100, y: 200 }, + { x: 200, y: 300 } + ] + ``` - 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`. + - `x: number` - - `string` + The x-coordinate. - - `"1024x1024" or "1024x1536" or "1536x1024" or "auto"` + - `y: 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 y-coordinate. - - `"1024x1024"` + - `type: "drag"` - - `"1024x1536"` + Specifies the event type. For a drag action, this property is always set to `drag`. - - `"1536x1024"` + - `"drag"` - - `"auto"` + - `keys: optional array of string` - - `LocalShell object { type }` + The keys being held while dragging the mouse. - A tool that allows the model to execute shell commands in a local environment. + - `Keypress object { keys, type }` - - `type: "local_shell"` + A collection of keypresses the model would like to perform. - The type of the local shell tool. Always `local_shell`. + - `keys: array of string` - - `"local_shell"` + The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. - - `Shell object { type, allowed_callers, environment }` + - `type: "keypress"` - A tool that allows the model to execute shell commands. + Specifies the event type. For a keypress action, this property is always set to `keypress`. - - `type: "shell"` + - `"keypress"` - The type of the shell tool. Always `shell`. + - `Move object { type, x, y, keys }` - - `"shell"` + A mouse move action. - - `allowed_callers: optional array of "direct" or "programmatic"` + - `type: "move"` - The tool invocation context(s). + Specifies the event type. For a move action, this property is always set to `move`. - - `"direct"` + - `"move"` - - `"programmatic"` + - `x: number` - - `environment: optional ContainerAuto or LocalEnvironment or ContainerReference` + The x-coordinate to move to. - - `ContainerAuto object { type, file_ids, memory_limit, 2 more }` + - `y: number` - - `LocalEnvironment object { type, skills }` + The y-coordinate to move to. - - `ContainerReference object { container_id, type }` + - `keys: optional array of string` - - `Custom object { name, type, allowed_callers, 3 more }` + The keys being held while moving the mouse. - 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) + - `Screenshot object { type }` - - `name: string` + A screenshot action. - The name of the custom tool, used to identify it in tool calls. + - `type: "screenshot"` - - `type: "custom"` + Specifies the event type. For a screenshot action, this property is always set to `screenshot`. - The type of the custom tool. Always `custom`. + - `"screenshot"` - - `"custom"` + - `Scroll object { scroll_x, scroll_y, type, 3 more }` - - `allowed_callers: optional array of "direct" or "programmatic"` + A scroll action. - The tool invocation context(s). + - `scroll_x: number` - - `"direct"` + The horizontal scroll distance. - - `"programmatic"` + - `scroll_y: number` - - `defer_loading: optional boolean` + The vertical scroll distance. - Whether this tool should be deferred and discovered via tool search. + - `type: "scroll"` - - `description: optional string` + Specifies the event type. For a scroll action, this property is always set to `scroll`. - Optional description of the custom tool, used to provide more context. + - `"scroll"` - - `format: optional CustomToolInputFormat` + - `x: number` - The input format for the custom tool. Default is unconstrained text. + The x-coordinate where the scroll occurred. - - `Namespace object { description, name, tools, type }` + - `y: number` - Groups function/custom tools under a shared namespace. + The y-coordinate where the scroll occurred. - - `description: string` + - `keys: optional array of string` - A description of the namespace shown to the model. + The keys being held while scrolling. - - `name: string` + - `Type object { text, type }` - The namespace name used in tool calls (for example, `crm`). + An action to type in text. - - `tools: array of object { name, type, allowed_callers, 5 more } or object { name, type, allowed_callers, 3 more }` + - `text: string` - The function/custom tools available inside this namespace. + The text to type. - - `Function object { name, type, allowed_callers, 5 more }` + - `type: "type"` - - `name: string` + Specifies the event type. For a type action, this property is always set to `type`. - - `type: "function"` + - `"type"` - - `"function"` + - `Wait object { type }` - - `allowed_callers: optional array of "direct" or "programmatic"` + A wait action. - The tool invocation context(s). + - `type: "wait"` - - `"direct"` + Specifies the event type. For a wait action, this property is always set to `wait`. - - `"programmatic"` + - `"wait"` - - `defer_loading: optional boolean` + - `actions: optional ComputerActionList` - Whether this function should be deferred and discovered via tool search. + Flattened batched actions for `computer_use`. Each action includes an + `type` discriminator and action-specific fields. - - `description: optional string` + - `Click object { button, type, x, 2 more }` - - `output_schema: optional map[unknown]` + A click action. - A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. + - `DoubleClick object { keys, type, x, y }` - - `parameters: optional unknown` + A double click action. - - `strict: optional boolean` + - `Drag object { path, type, keys }` - 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 drag action. - - `Custom object { name, type, allowed_callers, 3 more }` + - `Keypress object { keys, 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 collection of keypresses the model would like to perform. - - `name: string` + - `Move object { type, x, y, keys }` - The name of the custom tool, used to identify it in tool calls. + A mouse move action. - - `type: "custom"` + - `Screenshot object { type }` - The type of the custom tool. Always `custom`. + A screenshot action. - - `"custom"` + - `Scroll object { scroll_x, scroll_y, type, 3 more }` - - `allowed_callers: optional array of "direct" or "programmatic"` + A scroll action. - The tool invocation context(s). + - `Type object { text, type }` - - `"direct"` + An action to type in text. - - `"programmatic"` + - `Wait object { type }` - - `defer_loading: optional boolean` + A wait action. - Whether this tool should be deferred and discovered via tool search. + - `ComputerCallOutput object { id, call_id, output, 4 more }` - - `description: optional string` + - `id: string` - Optional description of the custom tool, used to provide more context. + The unique ID of the computer call tool output. - - `format: optional CustomToolInputFormat` + - `call_id: string` - The input format for the custom tool. Default is unconstrained text. + The ID of the computer tool call that produced the output. - - `type: "namespace"` + - `output: ResponseComputerToolCallOutputScreenshot` - The type of the tool. Always `namespace`. + A computer screenshot image used with the computer use tool. - - `"namespace"` + - `type: "computer_screenshot"` - - `ToolSearch object { type, description, execution, parameters }` + Specifies the event type. For a computer screenshot, this property is + always set to `computer_screenshot`. - Hosted or BYOT tool search configuration for deferred tools. + - `"computer_screenshot"` - - `type: "tool_search"` + - `file_id: optional string` - The type of the tool. Always `tool_search`. + The identifier of an uploaded file that contains the screenshot. - - `"tool_search"` + - `image_url: optional string` - - `description: optional string` + The URL of the screenshot image. - Description shown to the model for a client-executed tool search tool. + - `status: "completed" or "incomplete" or "failed" or "in_progress"` - - `execution: optional "server" or "client"` + The status of the message input. One of `in_progress`, `completed`, or + `incomplete`. Populated when input items are returned via API. - Whether tool search is executed by the server or by the client. + - `"completed"` - - `"server"` + - `"incomplete"` - - `"client"` + - `"failed"` - - `parameters: optional unknown` + - `"in_progress"` - Parameter schema for a client-executed tool search tool. + - `type: "computer_call_output"` - - `WebSearchPreview object { type, search_content_types, search_context_size, user_location }` + The type of the computer tool call output. Always `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). + - `"computer_call_output"` - - `type: "web_search_preview" or "web_search_preview_2025_03_11"` + - `acknowledged_safety_checks: optional array of object { id, code, message }` - The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. + The safety checks reported by the API that have been acknowledged by the + developer. - - `"web_search_preview"` + - `id: string` - - `"web_search_preview_2025_03_11"` + The ID of the pending safety check. - - `search_content_types: optional array of "text" or "image"` + - `code: optional string` - - `"text"` + The type of the pending safety check. - - `"image"` + - `message: optional string` - - `search_context_size: optional "low" or "medium" or "high"` + Details about the pending safety check. - 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. + - `created_by: optional string` - - `"low"` + The identifier of the actor that created the item. - - `"medium"` + - `Reasoning object { id, summary, type, 3 more }` - - `"high"` + 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). - - `user_location: optional object { type, city, country, 2 more }` + - `id: string` - The user's location. + The unique identifier of the reasoning content. - - `type: "approximate"` + - `summary: array of SummaryTextContent` - The type of location approximation. Always `approximate`. + Reasoning summary content. - - `"approximate"` + - `text: string` - - `city: optional string` + A summary of the reasoning output from the model so far. - Free text input for the city of the user, e.g. `San Francisco`. + - `type: "summary_text"` - - `country: optional string` + The type of the object. Always `summary_text`. - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + - `type: "reasoning"` - - `region: optional string` + The type of the object. Always `reasoning`. - Free text input for the region of the user, e.g. `California`. + - `"reasoning"` - - `timezone: optional string` + - `content: optional array of object { text, type }` - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + Reasoning text content. - - `ApplyPatch object { type, allowed_callers }` + - `text: string` - Allows the assistant to create, delete, or update files using unified diffs. + The reasoning text from the model. - - `type: "apply_patch"` + - `type: "reasoning_text"` - The type of the tool. Always `apply_patch`. + The type of the reasoning text. Always `reasoning_text`. - - `"apply_patch"` + - `"reasoning_text"` - - `allowed_callers: optional array of "direct" or "programmatic"` + - `encrypted_content: optional string` - The tool invocation context(s). + The encrypted content of the reasoning item - populated when a response is + generated with `reasoning.encrypted_content` in the `include` parameter. - - `"direct"` + - `status: optional "in_progress" or "completed" or "incomplete"` - - `"programmatic"` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `type: "additional_tools"` + - `"in_progress"` - The type of the item. Always `additional_tools`. + - `"completed"` - - `"additional_tools"` + - `"incomplete"` - `Compaction object { id, encrypted_content, type, created_by }` - A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). + A compaction item generated by the [`v1/responses/compact` API](/docs/api-reference/responses/compact). - `id: string` @@ -7767,36 +7519,6 @@ Compact a response 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. @@ -8302,59 +8024,6 @@ Compact a response 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. @@ -8449,6 +8118,59 @@ Compact a response 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, 4 more }` A call to a custom tool created by the model. @@ -8499,11 +8221,9 @@ Compact a response The namespace of the custom tool being called. - - `CustomToolCallOutput object { id, call_id, output, 4 more }` - - - `id: string` + - `CustomToolCallOutput object { call_id, output, type, 2 more }` - The unique ID of the custom tool call output item. + The output of a custom tool call from your code, being sent back to the model. - `call_id: string` @@ -8528,29 +8248,22 @@ Compact a response - `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). + An image input to the model. Learn about [image inputs](/docs/guides/vision). - `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` + + The unique ID of the custom tool call output in the OpenAI platform. + - `caller: optional object { type } or object { caller_id, type }` The execution context that produced this tool call. @@ -8575,10 +8288,6 @@ Compact a response - `"program"` - - `created_by: optional string` - - The identifier of the actor that created the item. - - `usage: ResponseUsage` Token accounting for the compaction pass, including cached, reasoning, and total tokens. @@ -8598,7 +8307,7 @@ Compact a response - `cached_tokens: number` The number of tokens that were retrieved from the cache. - [More on prompt caching](https://platform.openai.com/docs/guides/prompt-caching). + [More on prompt caching](/docs/guides/prompt-caching). - `output_tokens: number` @@ -8640,37 +8349,14 @@ 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": "output_text", - "logprobs": [ - { - "token": "token", - "bytes": [ - 0 - ], - "logprob": 0, - "top_logprobs": [ - { - "token": "token", - "bytes": [ - 0 - ], - "logprob": 0 - } - ] + "type": "input_text", + "prompt_cache_breakpoint": { + "mode": "explicit" } - ] } ], - "role": "assistant", + "role": "unknown", "status": "in_progress", "type": "message", "phase": "commentary"