diff --git a/en/resources/conversations/index.md b/en/resources/conversations/index.md index 5171aef..9fd193d 100644 --- a/en/resources/conversations/index.md +++ b/en/resources/conversations/index.md @@ -4,11 +4,11 @@ **post** `/conversations` -Create a conversation. +Create a conversation ### Body Parameters -- `items: optional array of EasyInputMessage or object { content, role, status, type } or ResponseOutputMessage or 27 more` +- `items: optional array of EasyInputMessage or object { content, role, status, type } or ResponseOutputMessage or 29 more` Initial items to include in the conversation context. You may add up to 20 items at a time. @@ -34,7 +34,7 @@ Create a conversation. A list of one or many input items to the model, containing different content types. - - `ResponseInputText object { text, type }` + - `ResponseInputText object { text, type, prompt_cache_breakpoint }` A text input to the model. @@ -48,9 +48,19 @@ Create a conversation. - `"input_text"` - - `ResponseInputImage object { detail, type, file_id, image_url }` + - `prompt_cache_breakpoint: optional object { mode }` - An image input to the model. Learn about [image inputs](/docs/guides/vision). + 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"` + + - `ResponseInputImage object { detail, type, file_id, 2 more }` + + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - `detail: "low" or "high" or "auto" or "original"` @@ -78,7 +88,17 @@ Create a conversation. The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - - `ResponseInputFile object { type, detail, file_data, 3 more }` + - `prompt_cache_breakpoint: optional object { mode }` + + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + + - `mode: "explicit"` + + The breakpoint mode. Always `explicit`. + + - `"explicit"` + + - `ResponseInputFile object { type, detail, file_data, 4 more }` A file input to the model. @@ -88,9 +108,11 @@ Create a conversation. - `"input_file"` - - `detail: optional "low" or "high"` + - `detail: optional "auto" or "low" or "high"` - The detail level of the file to be sent to the model. Use `low` for the default rendering behavior, or `high` to render the file at higher quality. Defaults to `low`. + The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. + + - `"auto"` - `"low"` @@ -112,6 +134,16 @@ Create a conversation. The name of the file to be sent to the model. + - `prompt_cache_breakpoint: optional object { mode }` + + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + + - `mode: "explicit"` + + The breakpoint mode. Always `explicit`. + + - `"explicit"` + - `role: "user" or "assistant" or "system" or "developer"` The role of the message input. One of `user`, `assistant`, `system`, or @@ -191,7 +223,7 @@ Create a conversation. The content of the output message. - - `ResponseOutputText object { annotations, logprobs, text, type }` + - `ResponseOutputText object { annotations, text, type, logprobs }` A text output from the model. @@ -295,15 +327,17 @@ Create a conversation. - `"file_path"` - - `logprobs: array of object { token, bytes, logprob, top_logprobs }` + - `text: string` - - `token: string` + The text output from the model. - - `bytes: array of number` + - `type: "output_text"` - - `logprob: number` + The type of the output text. Always `output_text`. - - `top_logprobs: array of object { token, bytes, logprob }` + - `"output_text"` + + - `logprobs: optional array of object { token, bytes, logprob, top_logprobs }` - `token: string` @@ -311,15 +345,13 @@ Create a conversation. - `logprob: number` - - `text: string` - - The text output from the model. + - `top_logprobs: array of object { token, bytes, logprob }` - - `type: "output_text"` + - `token: string` - The type of the output text. Always `output_text`. + - `bytes: array of number` - - `"output_text"` + - `logprob: number` - `ResponseOutputRefusal object { refusal, type }` @@ -371,7 +403,7 @@ Create a conversation. - `FileSearchCall object { id, queries, status, 2 more }` The results of a file search tool call. See the - [file search guide](/docs/guides/tools-file-search) for more information. + [file search guide](https://platform.openai.com/docs/guides/tools-file-search) for more information. - `id: string` @@ -439,7 +471,7 @@ Create a conversation. - `ComputerCall object { id, call_id, pending_safety_checks, 4 more }` A tool call to a computer use tool. See the - [computer use guide](/docs/guides/tools-computer-use) for more information. + [computer use guide](https://platform.openai.com/docs/guides/tools-computer-use) for more information. - `id: string` @@ -482,7 +514,7 @@ Create a conversation. - `"computer_call"` - - `action: optional ComputerAction` + - `action: optional object { button, type, x, 2 more } or object { keys, type, x, y } or object { path, type, keys } or 6 more` A click action. @@ -686,38 +718,193 @@ Create a conversation. 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. @@ -784,7 +971,7 @@ Create a conversation. - `WebSearchCall object { id, action, status, type }` The results of a web search tool call. See the - [web search guide](/docs/guides/tools-web-search) for more information. + [web search guide](https://platform.openai.com/docs/guides/tools-web-search) for more information. - `id: string` @@ -877,10 +1064,10 @@ Create a conversation. - `"web_search_call"` - - `FunctionCall object { arguments, call_id, name, 4 more }` + - `FunctionCall object { arguments, call_id, name, 5 more }` A tool call to run a function. See the - [function calling guide](/docs/guides/function-calling) for more information. + [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. - `arguments: string` @@ -904,6 +1091,26 @@ Create a conversation. 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. @@ -919,7 +1126,7 @@ Create a conversation. - `"incomplete"` - - `FunctionCallOutput object { call_id, output, type, 2 more }` + - `FunctionCallOutput object { call_id, output, type, 3 more }` The output of a function tool call. @@ -927,7 +1134,7 @@ Create a conversation. The unique ID of the function tool call generated by the model. - - `output: string or array of ResponseInputTextContent or ResponseInputImageContent or ResponseInputFileContent` + - `output: string or ResponseFunctionCallOutputItemList` Text, image, or file output of the function tool call. @@ -935,11 +1142,11 @@ Create a conversation. A JSON string of the output of the function tool call. - - `array of ResponseInputTextContent or ResponseInputImageContent or ResponseInputFileContent` + - `ResponseFunctionCallOutputItemList = array of ResponseFunctionCallOutputItem` An array of content outputs (text, image, file) for the function tool call. - - `ResponseInputTextContent object { text, type }` + - `ResponseInputTextContent object { text, type, prompt_cache_breakpoint }` A text input to the model. @@ -953,9 +1160,19 @@ Create a conversation. - `"input_text"` - - `ResponseInputImageContent object { type, detail, file_id, image_url }` + - `prompt_cache_breakpoint: optional object { mode }` + + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + + - `mode: "explicit"` - An image input to the model. Learn about [image inputs](/docs/guides/vision) + The breakpoint mode. Always `explicit`. + + - `"explicit"` + + - `ResponseInputImageContent object { type, detail, file_id, 2 more }` + + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) - `type: "input_image"` @@ -983,7 +1200,17 @@ Create a conversation. The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - - `ResponseInputFileContent object { type, detail, file_data, 3 more }` + - `prompt_cache_breakpoint: optional object { mode }` + + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + + - `mode: "explicit"` + + The breakpoint mode. Always `explicit`. + + - `"explicit"` + + - `ResponseInputFileContent object { type, detail, file_data, 4 more }` A file input to the model. @@ -993,9 +1220,11 @@ Create a conversation. - `"input_file"` - - `detail: optional "low" or "high"` + - `detail: optional "auto" or "low" or "high"` - The detail level of the file to be sent to the model. Use `low` for the default rendering behavior, or `high` to render the file at higher quality. Defaults to `low`. + The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. + + - `"auto"` - `"low"` @@ -1017,6 +1246,16 @@ Create a conversation. The name of the file to be sent to the model. + - `prompt_cache_breakpoint: optional object { mode }` + + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + + - `mode: "explicit"` + + The breakpoint mode. Always `explicit`. + + - `"explicit"` + - `type: "function_call_output"` The type of the function tool call output. Always `function_call_output`. @@ -1027,6 +1266,30 @@ Create a conversation. The unique ID of the function tool call output. Populated when this item is returned via API. + - `caller: optional object { type } or object { caller_id, type }` + + The execution context that produced this tool call. + + - `Direct object { type }` + + - `type: "direct"` + + The caller type. Always `direct`. + + - `"direct"` + + - `Program object { caller_id, type }` + + - `caller_id: string` + + The call ID of the program item that produced this tool call. + + - `type: "program"` + + The caller type. Always `program`. + + - `"program"` + - `status: optional "in_progress" or "completed" or "incomplete"` The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. @@ -1077,11 +1340,11 @@ Create a conversation. - `ToolSearchOutput object { tools, type, id, 3 more }` - - `tools: array of object { name, parameters, strict, 3 more } or object { type, vector_store_ids, filters, 2 more } or object { type } or 12 more` + - `tools: array of object { name, parameters, strict, 5 more } or object { type, vector_store_ids, filters, 2 more } or object { type } or 13 more` The loaded tool definitions returned by the tool search output. - - `Function object { name, parameters, strict, 3 more }` + - `Function object { name, parameters, strict, 5 more }` Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). @@ -1095,7 +1358,7 @@ Create a conversation. - `strict: boolean` - Whether to enforce strict parameter validation. Default `true`. + Whether strict parameter validation is enforced for this function tool. - `type: "function"` @@ -1103,6 +1366,14 @@ Create a conversation. - `"function"` + - `allowed_callers: optional array of "direct" or "programmatic"` + + The tool invocation context(s). + + - `"direct"` + + - `"programmatic"` + - `defer_loading: optional boolean` Whether this function is deferred and loaded via tool search. @@ -1111,6 +1382,10 @@ Create a conversation. 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). @@ -1281,7 +1556,7 @@ Create a conversation. - `WebSearch object { type, filters, search_context_size, user_location }` Search the Internet for sources related to the prompt. Learn more about the - [web search tool](/docs/guides/tools-web-search). + [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - `type: "web_search" or "web_search_2025_08_26"` @@ -1338,10 +1613,10 @@ Create a conversation. - `"approximate"` - - `Mcp object { server_label, type, allowed_tools, 8 more }` + - `Mcp object { server_label, type, allowed_callers, 9 more }` Give the model access to additional tools via remote Model Context Protocol - (MCP) servers. [Learn more about MCP](/docs/guides/tools-remote-mcp). + (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). - `server_label: string` @@ -1353,6 +1628,14 @@ Create a conversation. - `"mcp"` + - `allowed_callers: optional array of "direct" or "programmatic"` + + The tool invocation context(s). + + - `"direct"` + + - `"programmatic"` + - `allowed_tools: optional array of string or object { read_only, tool_names }` List of allowed tool names or a filter object. @@ -1385,7 +1668,7 @@ Create a conversation. Identifier for service connectors, like those available in ChatGPT. One of `server_url`, `connector_id`, or `tunnel_id` must be provided. Learn more - about service connectors [here](/docs/guides/tools-remote-mcp#connectors). + about service connectors [here](https://platform.openai.com/docs/guides/tools-remote-mcp#connectors). Currently supported `connector_id` values are: @@ -1485,7 +1768,7 @@ Create a conversation. The Secure MCP Tunnel ID to use instead of a direct server URL. One of `server_url`, `connector_id`, or `tunnel_id` must be provided. - - `CodeInterpreter object { container, type }` + - `CodeInterpreter object { container, type, allowed_callers }` A tool that runs Python code to help generate a response to a prompt. @@ -1571,6 +1854,22 @@ Create a conversation. - `"code_interpreter"` + - `allowed_callers: optional array of "direct" or "programmatic"` + + The tool invocation context(s). + + - `"direct"` + + - `"programmatic"` + + - `ProgrammaticToolCalling object { type }` + + - `type: "programmatic_tool_calling"` + + The type of the tool. Always `programmatic_tool_calling`. + + - `"programmatic_tool_calling"` + - `ImageGeneration object { type, action, background, 9 more }` A tool that generates images using the GPT image models. @@ -1593,8 +1892,19 @@ Create a conversation. - `background: optional "transparent" or "opaque" or "auto"` - Background type for the generated image. One of `transparent`, - `opaque`, or `auto`. Default: `auto`. + Allows to set transparency for the background of the generated image(s). + This parameter is only supported for GPT image models that support + transparent backgrounds. Must be one of `transparent`, `opaque`, or + `auto` (default value). When `auto` is used, the model will + automatically determine the best background for the image. + + `gpt-image-2` and `gpt-image-2-2026-04-21` do not support + transparent backgrounds. Requests with `background` set to + `transparent` will return an error for these models; use `opaque` or + `auto` instead. + + If `transparent`, the output format needs to support transparency, + so it should be set to either `png` (default value) or `webp`. - `"transparent"` @@ -1623,13 +1933,13 @@ Create a conversation. Base64-encoded mask image. - - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` + - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-2" or 3 more` The image generation model to use. Default: `gpt-image-1`. - `string` - - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` + - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-2" or 3 more` The image generation model to use. Default: `gpt-image-1`. @@ -1637,8 +1947,14 @@ Create a conversation. - `"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`. @@ -1707,7 +2023,7 @@ Create a conversation. - `"local_shell"` - - `Shell object { type, environment }` + - `Shell object { type, allowed_callers, environment }` A tool that allows the model to execute shell commands. @@ -1717,9 +2033,17 @@ Create a conversation. - `"shell"` - - `environment: optional ContainerAuto or LocalEnvironment or ContainerReference` + - `allowed_callers: optional array of "direct" or "programmatic"` - - `ContainerAuto object { type, file_ids, memory_limit, 2 more }` + The tool invocation context(s). + + - `"direct"` + + - `"programmatic"` + + - `environment: optional ContainerAuto or LocalEnvironment or ContainerReference` + + - `ContainerAuto object { type, file_ids, memory_limit, 2 more }` - `type: "container_auto"` @@ -1843,9 +2167,9 @@ Create a conversation. - `"container_reference"` - - `Custom object { name, type, defer_loading, 2 more }` + - `Custom object { name, type, allowed_callers, 3 more }` - A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) - `name: string` @@ -1857,6 +2181,14 @@ Create a conversation. - `"custom"` + - `allowed_callers: optional array of "direct" or "programmatic"` + + The tool invocation context(s). + + - `"direct"` + + - `"programmatic"` + - `defer_loading: optional boolean` Whether this tool should be deferred and discovered via tool search. @@ -1913,11 +2245,11 @@ Create a conversation. The namespace name used in tool calls (for example, `crm`). - - `tools: array of object { name, type, defer_loading, 3 more } or object { name, type, defer_loading, 2 more }` + - `tools: array of object { name, type, allowed_callers, 5 more } or object { name, type, allowed_callers, 3 more }` The function/custom tools available inside this namespace. - - `Function object { name, type, defer_loading, 3 more }` + - `Function object { name, type, allowed_callers, 5 more }` - `name: string` @@ -1925,19 +2257,33 @@ Create a conversation. - `"function"` + - `allowed_callers: optional array of "direct" or "programmatic"` + + The tool invocation context(s). + + - `"direct"` + + - `"programmatic"` + - `defer_loading: optional boolean` Whether this function should be deferred and discovered via tool search. - `description: optional string` + - `output_schema: optional map[unknown]` + + A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. + - `parameters: optional unknown` - `strict: optional boolean` - - `Custom object { name, type, defer_loading, 2 more }` + Whether to enforce strict parameter validation. If omitted, Responses attempts to use strict validation when the schema is compatible, and falls back to non-strict validation otherwise. - A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) + - `Custom object { name, type, allowed_callers, 3 more }` + + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) - `name: string` @@ -1949,6 +2295,14 @@ Create a conversation. - `"custom"` + - `allowed_callers: optional array of "direct" or "programmatic"` + + The tool invocation context(s). + + - `"direct"` + + - `"programmatic"` + - `defer_loading: optional boolean` Whether this tool should be deferred and discovered via tool search. @@ -2047,7 +2401,7 @@ Create a conversation. The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - - `ApplyPatch object { type }` + - `ApplyPatch object { type, allowed_callers }` Allows the assistant to create, delete, or update files using unified diffs. @@ -2057,6 +2411,14 @@ Create a conversation. - `"apply_patch"` + - `allowed_callers: optional array of "direct" or "programmatic"` + + The tool invocation context(s). + + - `"direct"` + + - `"programmatic"` + - `type: "tool_search_output"` The item type. Always `tool_search_output`. @@ -2097,11 +2459,11 @@ Create a conversation. - `"developer"` - - `tools: array of object { name, parameters, strict, 3 more } or object { type, vector_store_ids, filters, 2 more } or object { type } or 12 more` + - `tools: array of object { name, parameters, strict, 5 more } or object { type, vector_store_ids, filters, 2 more } or object { type } or 13 more` A list of additional tools made available at this item. - - `Function object { name, parameters, strict, 3 more }` + - `Function object { name, parameters, strict, 5 more }` Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). @@ -2115,7 +2477,7 @@ Create a conversation. - `strict: boolean` - Whether to enforce strict parameter validation. Default `true`. + Whether strict parameter validation is enforced for this function tool. - `type: "function"` @@ -2123,6 +2485,14 @@ Create a conversation. - `"function"` + - `allowed_callers: optional array of "direct" or "programmatic"` + + The tool invocation context(s). + + - `"direct"` + + - `"programmatic"` + - `defer_loading: optional boolean` Whether this function is deferred and loaded via tool search. @@ -2131,6 +2501,10 @@ Create a conversation. 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). @@ -2234,7 +2608,7 @@ Create a conversation. - `WebSearch object { type, filters, search_context_size, user_location }` Search the Internet for sources related to the prompt. Learn more about the - [web search tool](/docs/guides/tools-web-search). + [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - `type: "web_search" or "web_search_2025_08_26"` @@ -2291,10 +2665,10 @@ Create a conversation. - `"approximate"` - - `Mcp object { server_label, type, allowed_tools, 8 more }` + - `Mcp object { server_label, type, allowed_callers, 9 more }` Give the model access to additional tools via remote Model Context Protocol - (MCP) servers. [Learn more about MCP](/docs/guides/tools-remote-mcp). + (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). - `server_label: string` @@ -2306,6 +2680,14 @@ Create a conversation. - `"mcp"` + - `allowed_callers: optional array of "direct" or "programmatic"` + + The tool invocation context(s). + + - `"direct"` + + - `"programmatic"` + - `allowed_tools: optional array of string or object { read_only, tool_names }` List of allowed tool names or a filter object. @@ -2338,7 +2720,7 @@ Create a conversation. Identifier for service connectors, like those available in ChatGPT. One of `server_url`, `connector_id`, or `tunnel_id` must be provided. Learn more - about service connectors [here](/docs/guides/tools-remote-mcp#connectors). + about service connectors [here](https://platform.openai.com/docs/guides/tools-remote-mcp#connectors). Currently supported `connector_id` values are: @@ -2438,7 +2820,7 @@ Create a conversation. The Secure MCP Tunnel ID to use instead of a direct server URL. One of `server_url`, `connector_id`, or `tunnel_id` must be provided. - - `CodeInterpreter object { container, type }` + - `CodeInterpreter object { container, type, allowed_callers }` A tool that runs Python code to help generate a response to a prompt. @@ -2492,6 +2874,22 @@ Create a conversation. - `"code_interpreter"` + - `allowed_callers: optional array of "direct" or "programmatic"` + + The tool invocation context(s). + + - `"direct"` + + - `"programmatic"` + + - `ProgrammaticToolCalling object { type }` + + - `type: "programmatic_tool_calling"` + + The type of the tool. Always `programmatic_tool_calling`. + + - `"programmatic_tool_calling"` + - `ImageGeneration object { type, action, background, 9 more }` A tool that generates images using the GPT image models. @@ -2514,8 +2912,19 @@ Create a conversation. - `background: optional "transparent" or "opaque" or "auto"` - Background type for the generated image. One of `transparent`, - `opaque`, or `auto`. Default: `auto`. + Allows to set transparency for the background of the generated image(s). + This parameter is only supported for GPT image models that support + transparent backgrounds. Must be one of `transparent`, `opaque`, or + `auto` (default value). When `auto` is used, the model will + automatically determine the best background for the image. + + `gpt-image-2` and `gpt-image-2-2026-04-21` do not support + transparent backgrounds. Requests with `background` set to + `transparent` will return an error for these models; use `opaque` or + `auto` instead. + + If `transparent`, the output format needs to support transparency, + so it should be set to either `png` (default value) or `webp`. - `"transparent"` @@ -2544,13 +2953,13 @@ Create a conversation. Base64-encoded mask image. - - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` + - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-2" or 3 more` The image generation model to use. Default: `gpt-image-1`. - `string` - - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` + - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-2" or 3 more` The image generation model to use. Default: `gpt-image-1`. @@ -2558,8 +2967,14 @@ Create a conversation. - `"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`. @@ -2628,7 +3043,7 @@ Create a conversation. - `"local_shell"` - - `Shell object { type, environment }` + - `Shell object { type, allowed_callers, environment }` A tool that allows the model to execute shell commands. @@ -2638,6 +3053,14 @@ Create a conversation. - `"shell"` + - `allowed_callers: optional array of "direct" or "programmatic"` + + The tool invocation context(s). + + - `"direct"` + + - `"programmatic"` + - `environment: optional ContainerAuto or LocalEnvironment or ContainerReference` - `ContainerAuto object { type, file_ids, memory_limit, 2 more }` @@ -2646,9 +3069,9 @@ Create a conversation. - `ContainerReference object { container_id, type }` - - `Custom object { name, type, defer_loading, 2 more }` + - `Custom object { name, type, allowed_callers, 3 more }` - A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) - `name: string` @@ -2660,6 +3083,14 @@ Create a conversation. - `"custom"` + - `allowed_callers: optional array of "direct" or "programmatic"` + + The tool invocation context(s). + + - `"direct"` + + - `"programmatic"` + - `defer_loading: optional boolean` Whether this tool should be deferred and discovered via tool search. @@ -2684,11 +3115,11 @@ Create a conversation. The namespace name used in tool calls (for example, `crm`). - - `tools: array of object { name, type, defer_loading, 3 more } or object { name, type, defer_loading, 2 more }` + - `tools: array of object { name, type, allowed_callers, 5 more } or object { name, type, allowed_callers, 3 more }` The function/custom tools available inside this namespace. - - `Function object { name, type, defer_loading, 3 more }` + - `Function object { name, type, allowed_callers, 5 more }` - `name: string` @@ -2696,19 +3127,33 @@ Create a conversation. - `"function"` + - `allowed_callers: optional array of "direct" or "programmatic"` + + The tool invocation context(s). + + - `"direct"` + + - `"programmatic"` + - `defer_loading: optional boolean` Whether this function should be deferred and discovered via tool search. - `description: optional string` + - `output_schema: optional map[unknown]` + + A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. + - `parameters: optional unknown` - `strict: optional boolean` - - `Custom object { name, type, defer_loading, 2 more }` + Whether to enforce strict parameter validation. If omitted, Responses attempts to use strict validation when the schema is compatible, and falls back to non-strict validation otherwise. - A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) + - `Custom object { name, type, allowed_callers, 3 more }` + + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) - `name: string` @@ -2720,6 +3165,14 @@ Create a conversation. - `"custom"` + - `allowed_callers: optional array of "direct" or "programmatic"` + + The tool invocation context(s). + + - `"direct"` + + - `"programmatic"` + - `defer_loading: optional boolean` Whether this tool should be deferred and discovered via tool search. @@ -2818,7 +3271,7 @@ Create a conversation. The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - - `ApplyPatch object { type }` + - `ApplyPatch object { type, allowed_callers }` Allows the assistant to create, delete, or update files using unified diffs. @@ -2828,6 +3281,14 @@ Create a conversation. - `"apply_patch"` + - `allowed_callers: optional array of "direct" or "programmatic"` + + The tool invocation context(s). + + - `"direct"` + + - `"programmatic"` + - `type: "additional_tools"` The item type. Always `additional_tools`. @@ -2843,13 +3304,13 @@ Create a conversation. A description of the chain of thought used by a reasoning model while generating a response. Be sure to include these items in your `input` to the Responses API for subsequent turns of a conversation if you are manually - [managing context](/docs/guides/conversation-state). + [managing context](https://platform.openai.com/docs/guides/conversation-state). - `id: string` The unique identifier of the reasoning content. - - `summary: array of SummaryTextContent` + - `summary: array of object { text, type }` Reasoning summary content. @@ -2901,7 +3362,7 @@ Create a conversation. - `Compaction object { encrypted_content, type, id }` - A compaction item generated by the [`v1/responses/compact` API](/docs/api-reference/responses/compact). + A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). - `encrypted_content: string` @@ -3102,7 +3563,7 @@ Create a conversation. - `"incomplete"` - - `ShellCall object { action, call_id, type, 3 more }` + - `ShellCall object { action, call_id, type, 4 more }` A tool representing a request to execute one or more shell commands. @@ -3136,6 +3597,30 @@ Create a conversation. The unique ID of the shell tool call. Populated when this item is returned via API. + - `caller: optional object { type } or object { caller_id, type }` + + The execution context that produced this tool call. + + - `Direct object { type }` + + - `type: "direct"` + + The caller type. Always `direct`. + + - `"direct"` + + - `Program object { caller_id, type }` + + - `caller_id: string` + + The call ID of the program item that produced this tool call. + + - `type: "program"` + + The caller type. Always `program`. + + - `"program"` + - `environment: optional LocalEnvironment or ContainerReference` The environment to execute the shell commands in. @@ -3154,7 +3639,7 @@ Create a conversation. - `"incomplete"` - - `ShellCallOutput object { call_id, output, type, 3 more }` + - `ShellCallOutput object { call_id, output, type, 4 more }` The streamed output items emitted by a shell tool call. @@ -3212,6 +3697,30 @@ Create a conversation. The unique ID of the shell tool call output. Populated when this item is returned via API. + - `caller: optional object { type } or object { caller_id, type }` + + The execution context that produced this tool call. + + - `Direct object { type }` + + - `type: "direct"` + + The caller type. Always `direct`. + + - `"direct"` + + - `Program object { caller_id, type }` + + - `caller_id: string` + + The call ID of the program item that produced this tool call. + + - `type: "program"` + + The caller type. Always `program`. + + - `"program"` + - `max_output_length: optional number` The maximum number of UTF-8 characters captured for this shell call's combined output. @@ -3226,7 +3735,7 @@ Create a conversation. - `"incomplete"` - - `ApplyPatchCall object { call_id, operation, status, 2 more }` + - `ApplyPatchCall object { call_id, operation, status, 3 more }` A tool call representing a request to create, delete, or update files using diff patches. @@ -3306,7 +3815,31 @@ Create a conversation. The unique ID of the apply patch tool call. Populated when this item is returned via API. - - `ApplyPatchCallOutput object { call_id, status, type, 2 more }` + - `caller: optional object { type } or object { caller_id, type }` + + The execution context that produced this tool call. + + - `Direct object { type }` + + - `type: "direct"` + + The caller type. Always `direct`. + + - `"direct"` + + - `Program object { caller_id, type }` + + - `caller_id: string` + + The call ID of the program item that produced this tool call. + + - `type: "program"` + + The caller type. Always `program`. + + - `"program"` + + - `ApplyPatchCallOutput object { call_id, status, type, 3 more }` The streamed output emitted by an apply patch tool call. @@ -3332,6 +3865,30 @@ Create a conversation. The unique ID of the apply patch tool call output. Populated when this item is returned via API. + - `caller: optional object { type } or object { caller_id, type }` + + The execution context that produced this tool call. + + - `Direct object { type }` + + - `type: "direct"` + + The caller type. Always `direct`. + + - `"direct"` + + - `Program object { caller_id, type }` + + - `caller_id: string` + + The call ID of the program item that produced this tool call. + + - `type: "program"` + + The caller type. Always `program`. + + - `"program"` + - `output: optional string` Optional human-readable log text from the apply patch tool (e.g., patch results or errors). @@ -3483,7 +4040,7 @@ Create a conversation. - `"failed"` - - `CustomToolCallOutput object { call_id, output, type, id }` + - `CustomToolCallOutput object { call_id, output, type, 2 more }` The output of a custom tool call from your code, being sent back to the model. @@ -3504,15 +4061,15 @@ Create a conversation. Text, image, or file output of the custom tool call. - - `ResponseInputText object { text, type }` + - `ResponseInputText object { text, type, prompt_cache_breakpoint }` A text input to the model. - - `ResponseInputImage object { detail, type, file_id, image_url }` + - `ResponseInputImage object { detail, type, file_id, 2 more }` - An image input to the model. Learn about [image inputs](/docs/guides/vision). + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - `ResponseInputFile object { type, detail, file_data, 3 more }` + - `ResponseInputFile object { type, detail, file_data, 4 more }` A file input to the model. @@ -3526,7 +4083,31 @@ Create a conversation. The unique ID of the custom tool call output in the OpenAI platform. - - `CustomToolCall object { call_id, input, name, 3 more }` + - `caller: optional object { type } or object { caller_id, type }` + + The execution context that produced this tool call. + + - `Direct object { type }` + + - `type: "direct"` + + The caller type. Always `direct`. + + - `"direct"` + + - `Program object { caller_id, type }` + + - `caller_id: string` + + The call ID of the program item that produced this tool call. + + - `type: "program"` + + The caller type. Always `program`. + + - `"program"` + + - `CustomToolCall object { call_id, input, name, 4 more }` A call to a custom tool created by the model. @@ -3552,6 +4133,26 @@ Create a conversation. The unique ID of the custom tool call in the OpenAI platform. + - `caller: optional object { type } or object { caller_id, type }` + + The execution context that produced this tool call. + + - `Direct object { type }` + + - `type: "direct"` + + - `"direct"` + + - `Program object { caller_id, type }` + + - `caller_id: string` + + The call ID of the program item that produced this tool call. + + - `type: "program"` + + - `"program"` + - `namespace: optional string` The namespace of the custom tool being called. @@ -3580,6 +4181,58 @@ Create a conversation. - `"item_reference"` + - `Program object { id, call_id, code, 2 more }` + + - `id: string` + + The unique ID of this program item. + + - `call_id: string` + + The stable call ID of the program item. + + - `code: string` + + The JavaScript source executed by programmatic tool calling. + + - `fingerprint: string` + + Opaque program replay fingerprint that must be round-tripped. + + - `type: "program"` + + The item type. Always `program`. + + - `"program"` + + - `ProgramOutput object { id, call_id, result, 2 more }` + + - `id: string` + + The unique ID of this program output item. + + - `call_id: string` + + The call ID of the program item. + + - `result: string` + + The result produced by the program item. + + - `status: "completed" or "incomplete"` + + The terminal status of the program output. + + - `"completed"` + + - `"incomplete"` + + - `type: "program_output"` + + The item type. Always `program_output`. + + - `"program_output"` + - `metadata: optional Metadata` Set of 16 key-value pairs that can be attached to an object. This can be @@ -3664,7 +4317,7 @@ curl https://api.openai.com/v1/conversations \ **get** `/conversations/{conversation_id}` -Get a conversation +Retrieve a conversation ### Path Parameters @@ -3823,7 +4476,7 @@ curl https://api.openai.com/v1/conversations/conv_123 \ **delete** `/conversations/{conversation_id}` -Delete a conversation. Items in the conversation will not be deleted. +Delete a conversation ### Path Parameters @@ -3880,7 +4533,7 @@ curl -X DELETE https://api.openai.com/v1/conversations/conv_123 \ ### Computer Screenshot Content -- `ComputerScreenshotContent object { detail, file_id, image_url, type }` +- `ComputerScreenshotContent object { detail, file_id, image_url, 2 more }` A screenshot of a computer. @@ -3910,6 +4563,16 @@ curl -X DELETE https://api.openai.com/v1/conversations/conv_123 \ - `"computer_screenshot"` + - `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"` + ### Conversation - `Conversation object { id, created_at, metadata, object }` @@ -3971,7 +4634,7 @@ curl -X DELETE https://api.openai.com/v1/conversations/conv_123 \ The content of the message - - `ResponseInputText object { text, type }` + - `ResponseInputText object { text, type, prompt_cache_breakpoint }` A text input to the model. @@ -3985,7 +4648,17 @@ curl -X DELETE https://api.openai.com/v1/conversations/conv_123 \ - `"input_text"` - - `ResponseOutputText object { annotations, logprobs, text, type }` + - `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 }` A text output from the model. @@ -4089,15 +4762,17 @@ curl -X DELETE https://api.openai.com/v1/conversations/conv_123 \ - `"file_path"` - - `logprobs: array of object { token, bytes, logprob, top_logprobs }` + - `text: string` - - `token: string` + The text output from the model. - - `bytes: array of number` + - `type: "output_text"` - - `logprob: number` + The type of the output text. Always `output_text`. - - `top_logprobs: array of object { token, bytes, logprob }` + - `"output_text"` + + - `logprobs: optional array of object { token, bytes, logprob, top_logprobs }` - `token: string` @@ -4105,15 +4780,13 @@ curl -X DELETE https://api.openai.com/v1/conversations/conv_123 \ - `logprob: number` - - `text: string` - - The text output from the model. + - `top_logprobs: array of object { token, bytes, logprob }` - - `type: "output_text"` + - `token: string` - The type of the output text. Always `output_text`. + - `bytes: array of number` - - `"output_text"` + - `logprob: number` - `TextContent object { text, type }` @@ -4167,9 +4840,9 @@ curl -X DELETE https://api.openai.com/v1/conversations/conv_123 \ - `"refusal"` - - `ResponseInputImage object { detail, type, file_id, image_url }` + - `ResponseInputImage object { detail, type, file_id, 2 more }` - An image input to the model. Learn about [image inputs](/docs/guides/vision). + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - `detail: "low" or "high" or "auto" or "original"` @@ -4197,7 +4870,17 @@ curl -X DELETE https://api.openai.com/v1/conversations/conv_123 \ The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - - `ComputerScreenshotContent object { detail, file_id, image_url, type }` + - `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"` + + - `ComputerScreenshotContent object { detail, file_id, image_url, 2 more }` A screenshot of a computer. @@ -4227,7 +4910,17 @@ curl -X DELETE https://api.openai.com/v1/conversations/conv_123 \ - `"computer_screenshot"` - - `ResponseInputFile object { type, detail, file_data, 3 more }` + - `prompt_cache_breakpoint: optional object { mode }` + + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + + - `mode: "explicit"` + + The breakpoint mode. Always `explicit`. + + - `"explicit"` + + - `ResponseInputFile object { type, detail, file_data, 4 more }` A file input to the model. @@ -4237,9 +4930,11 @@ curl -X DELETE https://api.openai.com/v1/conversations/conv_123 \ - `"input_file"` - - `detail: optional "low" or "high"` + - `detail: optional "auto" or "low" or "high"` + + The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. - The detail level of the file to be sent to the model. Use `low` for the default rendering behavior, or `high` to render the file at higher quality. Defaults to `low`. + - `"auto"` - `"low"` @@ -4261,6 +4956,16 @@ curl -X DELETE https://api.openai.com/v1/conversations/conv_123 \ The name of the file to be sent to the model. + - `prompt_cache_breakpoint: optional object { mode }` + + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + + - `mode: "explicit"` + + The breakpoint mode. Always `explicit`. + + - `"explicit"` + - `role: "unknown" or "user" or "assistant" or 5 more` The role of the message. One of `unknown`, `user`, `assistant`, `system`, `critic`, `discriminator`, `developer`, or `tool`. @@ -4339,7 +5044,7 @@ curl -X DELETE https://api.openai.com/v1/conversations/conv_123 \ **post** `/conversations/{conversation_id}/items` -Create items in a conversation with the given ID. +Create items ### Path Parameters @@ -4350,7 +5055,7 @@ Create items in a conversation with the given ID. - `include: optional array of ResponseIncludable` Additional fields to include in the response. See the `include` - parameter for [listing Conversation items above](/docs/api-reference/conversations/list-items#conversations_list_items-include) for more information. + parameter for [listing Conversation items above](https://platform.openai.com/docs/api-reference/conversations/list-items#conversations_list_items-include) for more information. - `"file_search_call.results"` @@ -4370,7 +5075,7 @@ Create items in a conversation with the given ID. ### Body Parameters -- `items: array of EasyInputMessage or object { content, role, status, type } or ResponseOutputMessage or 27 more` +- `items: array of EasyInputMessage or object { content, role, status, type } or ResponseOutputMessage or 29 more` The items to add to the conversation. You may add up to 20 items at a time. @@ -4396,7 +5101,7 @@ Create items in a conversation with the given ID. A list of one or many input items to the model, containing different content types. - - `ResponseInputText object { text, type }` + - `ResponseInputText object { text, type, prompt_cache_breakpoint }` A text input to the model. @@ -4410,9 +5115,19 @@ Create items in a conversation with the given ID. - `"input_text"` - - `ResponseInputImage object { detail, type, file_id, image_url }` + - `prompt_cache_breakpoint: optional object { mode }` + + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + + - `mode: "explicit"` - An image input to the model. Learn about [image inputs](/docs/guides/vision). + The breakpoint mode. Always `explicit`. + + - `"explicit"` + + - `ResponseInputImage object { detail, type, file_id, 2 more }` + + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - `detail: "low" or "high" or "auto" or "original"` @@ -4440,7 +5155,17 @@ Create items in a conversation with the given ID. The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - - `ResponseInputFile object { type, detail, file_data, 3 more }` + - `prompt_cache_breakpoint: optional object { mode }` + + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + + - `mode: "explicit"` + + The breakpoint mode. Always `explicit`. + + - `"explicit"` + + - `ResponseInputFile object { type, detail, file_data, 4 more }` A file input to the model. @@ -4450,9 +5175,11 @@ Create items in a conversation with the given ID. - `"input_file"` - - `detail: optional "low" or "high"` + - `detail: optional "auto" or "low" or "high"` - The detail level of the file to be sent to the model. Use `low` for the default rendering behavior, or `high` to render the file at higher quality. Defaults to `low`. + The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. + + - `"auto"` - `"low"` @@ -4474,6 +5201,16 @@ Create items in a conversation with the given ID. The name of the file to be sent to the model. + - `prompt_cache_breakpoint: optional object { mode }` + + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + + - `mode: "explicit"` + + The breakpoint mode. Always `explicit`. + + - `"explicit"` + - `role: "user" or "assistant" or "system" or "developer"` The role of the message input. One of `user`, `assistant`, `system`, or @@ -4553,7 +5290,7 @@ Create items in a conversation with the given ID. The content of the output message. - - `ResponseOutputText object { annotations, logprobs, text, type }` + - `ResponseOutputText object { annotations, text, type, logprobs }` A text output from the model. @@ -4657,7 +5394,17 @@ Create items in a conversation with the given ID. - `"file_path"` - - `logprobs: array of object { token, bytes, logprob, top_logprobs }` + - `text: string` + + The text output from the model. + + - `type: "output_text"` + + The type of the output text. Always `output_text`. + + - `"output_text"` + + - `logprobs: optional array of object { token, bytes, logprob, top_logprobs }` - `token: string` @@ -4673,21 +5420,11 @@ Create items in a conversation with the given ID. - `logprob: number` - - `text: string` + - `ResponseOutputRefusal object { refusal, type }` - The text output from the model. + A refusal 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. - - - `refusal: string` + - `refusal: string` The refusal explanation from the model. @@ -4733,7 +5470,7 @@ Create items in a conversation with the given ID. - `FileSearchCall object { id, queries, status, 2 more }` The results of a file search tool call. See the - [file search guide](/docs/guides/tools-file-search) for more information. + [file search guide](https://platform.openai.com/docs/guides/tools-file-search) for more information. - `id: string` @@ -4801,7 +5538,7 @@ Create items in a conversation with the given ID. - `ComputerCall object { id, call_id, pending_safety_checks, 4 more }` A tool call to a computer use tool. See the - [computer use guide](/docs/guides/tools-computer-use) for more information. + [computer use guide](https://platform.openai.com/docs/guides/tools-computer-use) for more information. - `id: string` @@ -4844,7 +5581,7 @@ Create items in a conversation with the given ID. - `"computer_call"` - - `action: optional ComputerAction` + - `action: optional object { button, type, x, 2 more } or object { keys, type, x, y } or object { path, type, keys } or 6 more` A click action. @@ -5048,38 +5785,193 @@ Create items in a conversation with the given ID. 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. @@ -5146,7 +6038,7 @@ Create items in a conversation with the given ID. - `WebSearchCall object { id, action, status, type }` The results of a web search tool call. See the - [web search guide](/docs/guides/tools-web-search) for more information. + [web search guide](https://platform.openai.com/docs/guides/tools-web-search) for more information. - `id: string` @@ -5239,10 +6131,10 @@ Create items in a conversation with the given ID. - `"web_search_call"` - - `FunctionCall object { arguments, call_id, name, 4 more }` + - `FunctionCall object { arguments, call_id, name, 5 more }` A tool call to run a function. See the - [function calling guide](/docs/guides/function-calling) for more information. + [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information. - `arguments: string` @@ -5266,6 +6158,26 @@ Create items in a conversation with the given ID. 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. @@ -5281,7 +6193,7 @@ Create items in a conversation with the given ID. - `"incomplete"` - - `FunctionCallOutput object { call_id, output, type, 2 more }` + - `FunctionCallOutput object { call_id, output, type, 3 more }` The output of a function tool call. @@ -5289,7 +6201,7 @@ Create items in a conversation with the given ID. The unique ID of the function tool call generated by the model. - - `output: string or array of ResponseInputTextContent or ResponseInputImageContent or ResponseInputFileContent` + - `output: string or ResponseFunctionCallOutputItemList` Text, image, or file output of the function tool call. @@ -5297,11 +6209,11 @@ Create items in a conversation with the given ID. A JSON string of the output of the function tool call. - - `array of ResponseInputTextContent or ResponseInputImageContent or ResponseInputFileContent` + - `ResponseFunctionCallOutputItemList = array of ResponseFunctionCallOutputItem` An array of content outputs (text, image, file) for the function tool call. - - `ResponseInputTextContent object { text, type }` + - `ResponseInputTextContent object { text, type, prompt_cache_breakpoint }` A text input to the model. @@ -5315,9 +6227,19 @@ Create items in a conversation with the given ID. - `"input_text"` - - `ResponseInputImageContent object { type, detail, file_id, image_url }` + - `prompt_cache_breakpoint: optional object { mode }` + + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + + - `mode: "explicit"` - An image input to the model. Learn about [image inputs](/docs/guides/vision) + The breakpoint mode. Always `explicit`. + + - `"explicit"` + + - `ResponseInputImageContent object { type, detail, file_id, 2 more }` + + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision) - `type: "input_image"` @@ -5345,7 +6267,17 @@ Create items in a conversation with the given ID. The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - - `ResponseInputFileContent object { type, detail, file_data, 3 more }` + - `prompt_cache_breakpoint: optional object { mode }` + + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + + - `mode: "explicit"` + + The breakpoint mode. Always `explicit`. + + - `"explicit"` + + - `ResponseInputFileContent object { type, detail, file_data, 4 more }` A file input to the model. @@ -5355,9 +6287,11 @@ Create items in a conversation with the given ID. - `"input_file"` - - `detail: optional "low" or "high"` + - `detail: optional "auto" or "low" or "high"` - The detail level of the file to be sent to the model. Use `low` for the default rendering behavior, or `high` to render the file at higher quality. Defaults to `low`. + The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. + + - `"auto"` - `"low"` @@ -5379,6 +6313,16 @@ Create items in a conversation with the given ID. The name of the file to be sent to the model. + - `prompt_cache_breakpoint: optional object { mode }` + + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + + - `mode: "explicit"` + + The breakpoint mode. Always `explicit`. + + - `"explicit"` + - `type: "function_call_output"` The type of the function tool call output. Always `function_call_output`. @@ -5389,6 +6333,30 @@ Create items in a conversation with the given ID. The unique ID of the function tool call output. Populated when this item is returned via API. + - `caller: optional object { type } or object { caller_id, type }` + + The execution context that produced this tool call. + + - `Direct object { type }` + + - `type: "direct"` + + The caller type. Always `direct`. + + - `"direct"` + + - `Program object { caller_id, type }` + + - `caller_id: string` + + The call ID of the program item that produced this tool call. + + - `type: "program"` + + The caller type. Always `program`. + + - `"program"` + - `status: optional "in_progress" or "completed" or "incomplete"` The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. @@ -5439,11 +6407,11 @@ Create items in a conversation with the given ID. - `ToolSearchOutput object { tools, type, id, 3 more }` - - `tools: array of object { name, parameters, strict, 3 more } or object { type, vector_store_ids, filters, 2 more } or object { type } or 12 more` + - `tools: array of object { name, parameters, strict, 5 more } or object { type, vector_store_ids, filters, 2 more } or object { type } or 13 more` The loaded tool definitions returned by the tool search output. - - `Function object { name, parameters, strict, 3 more }` + - `Function object { name, parameters, strict, 5 more }` Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). @@ -5457,7 +6425,7 @@ Create items in a conversation with the given ID. - `strict: boolean` - Whether to enforce strict parameter validation. Default `true`. + Whether strict parameter validation is enforced for this function tool. - `type: "function"` @@ -5465,6 +6433,14 @@ Create items in a conversation with the given ID. - `"function"` + - `allowed_callers: optional array of "direct" or "programmatic"` + + The tool invocation context(s). + + - `"direct"` + + - `"programmatic"` + - `defer_loading: optional boolean` Whether this function is deferred and loaded via tool search. @@ -5473,6 +6449,10 @@ Create items in a conversation with the given ID. 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). @@ -5643,7 +6623,7 @@ Create items in a conversation with the given ID. - `WebSearch object { type, filters, search_context_size, user_location }` Search the Internet for sources related to the prompt. Learn more about the - [web search tool](/docs/guides/tools-web-search). + [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - `type: "web_search" or "web_search_2025_08_26"` @@ -5700,10 +6680,10 @@ Create items in a conversation with the given ID. - `"approximate"` - - `Mcp object { server_label, type, allowed_tools, 8 more }` + - `Mcp object { server_label, type, allowed_callers, 9 more }` Give the model access to additional tools via remote Model Context Protocol - (MCP) servers. [Learn more about MCP](/docs/guides/tools-remote-mcp). + (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). - `server_label: string` @@ -5715,6 +6695,14 @@ Create items in a conversation with the given ID. - `"mcp"` + - `allowed_callers: optional array of "direct" or "programmatic"` + + The tool invocation context(s). + + - `"direct"` + + - `"programmatic"` + - `allowed_tools: optional array of string or object { read_only, tool_names }` List of allowed tool names or a filter object. @@ -5747,7 +6735,7 @@ Create items in a conversation with the given ID. Identifier for service connectors, like those available in ChatGPT. One of `server_url`, `connector_id`, or `tunnel_id` must be provided. Learn more - about service connectors [here](/docs/guides/tools-remote-mcp#connectors). + about service connectors [here](https://platform.openai.com/docs/guides/tools-remote-mcp#connectors). Currently supported `connector_id` values are: @@ -5847,7 +6835,7 @@ Create items in a conversation with the given ID. The Secure MCP Tunnel ID to use instead of a direct server URL. One of `server_url`, `connector_id`, or `tunnel_id` must be provided. - - `CodeInterpreter object { container, type }` + - `CodeInterpreter object { container, type, allowed_callers }` A tool that runs Python code to help generate a response to a prompt. @@ -5933,6 +6921,22 @@ Create items in a conversation with the given ID. - `"code_interpreter"` + - `allowed_callers: optional array of "direct" or "programmatic"` + + The tool invocation context(s). + + - `"direct"` + + - `"programmatic"` + + - `ProgrammaticToolCalling object { type }` + + - `type: "programmatic_tool_calling"` + + The type of the tool. Always `programmatic_tool_calling`. + + - `"programmatic_tool_calling"` + - `ImageGeneration object { type, action, background, 9 more }` A tool that generates images using the GPT image models. @@ -5955,8 +6959,19 @@ Create items in a conversation with the given ID. - `background: optional "transparent" or "opaque" or "auto"` - Background type for the generated image. One of `transparent`, - `opaque`, or `auto`. Default: `auto`. + Allows to set transparency for the background of the generated image(s). + This parameter is only supported for GPT image models that support + transparent backgrounds. Must be one of `transparent`, `opaque`, or + `auto` (default value). When `auto` is used, the model will + automatically determine the best background for the image. + + `gpt-image-2` and `gpt-image-2-2026-04-21` do not support + transparent backgrounds. Requests with `background` set to + `transparent` will return an error for these models; use `opaque` or + `auto` instead. + + If `transparent`, the output format needs to support transparency, + so it should be set to either `png` (default value) or `webp`. - `"transparent"` @@ -5985,13 +7000,13 @@ Create items in a conversation with the given ID. Base64-encoded mask image. - - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` + - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-2" or 3 more` The image generation model to use. Default: `gpt-image-1`. - `string` - - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` + - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-2" or 3 more` The image generation model to use. Default: `gpt-image-1`. @@ -5999,8 +7014,14 @@ Create items in a conversation with the given ID. - `"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`. @@ -6069,7 +7090,7 @@ Create items in a conversation with the given ID. - `"local_shell"` - - `Shell object { type, environment }` + - `Shell object { type, allowed_callers, environment }` A tool that allows the model to execute shell commands. @@ -6079,6 +7100,14 @@ Create items in a conversation with the given ID. - `"shell"` + - `allowed_callers: optional array of "direct" or "programmatic"` + + The tool invocation context(s). + + - `"direct"` + + - `"programmatic"` + - `environment: optional ContainerAuto or LocalEnvironment or ContainerReference` - `ContainerAuto object { type, file_ids, memory_limit, 2 more }` @@ -6205,9 +7234,9 @@ Create items in a conversation with the given ID. - `"container_reference"` - - `Custom object { name, type, defer_loading, 2 more }` + - `Custom object { name, type, allowed_callers, 3 more }` - A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) - `name: string` @@ -6219,6 +7248,14 @@ Create items in a conversation with the given ID. - `"custom"` + - `allowed_callers: optional array of "direct" or "programmatic"` + + The tool invocation context(s). + + - `"direct"` + + - `"programmatic"` + - `defer_loading: optional boolean` Whether this tool should be deferred and discovered via tool search. @@ -6275,11 +7312,11 @@ Create items in a conversation with the given ID. The namespace name used in tool calls (for example, `crm`). - - `tools: array of object { name, type, defer_loading, 3 more } or object { name, type, defer_loading, 2 more }` + - `tools: array of object { name, type, allowed_callers, 5 more } or object { name, type, allowed_callers, 3 more }` The function/custom tools available inside this namespace. - - `Function object { name, type, defer_loading, 3 more }` + - `Function object { name, type, allowed_callers, 5 more }` - `name: string` @@ -6287,19 +7324,33 @@ Create items in a conversation with the given ID. - `"function"` + - `allowed_callers: optional array of "direct" or "programmatic"` + + The tool invocation context(s). + + - `"direct"` + + - `"programmatic"` + - `defer_loading: optional boolean` Whether this function should be deferred and discovered via tool search. - `description: optional string` + - `output_schema: optional map[unknown]` + + A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. + - `parameters: optional unknown` - `strict: optional boolean` - - `Custom object { name, type, defer_loading, 2 more }` + Whether to enforce strict parameter validation. If omitted, Responses attempts to use strict validation when the schema is compatible, and falls back to non-strict validation otherwise. - A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) + - `Custom object { name, type, allowed_callers, 3 more }` + + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) - `name: string` @@ -6311,6 +7362,14 @@ Create items in a conversation with the given ID. - `"custom"` + - `allowed_callers: optional array of "direct" or "programmatic"` + + The tool invocation context(s). + + - `"direct"` + + - `"programmatic"` + - `defer_loading: optional boolean` Whether this tool should be deferred and discovered via tool search. @@ -6409,7 +7468,7 @@ Create items in a conversation with the given ID. The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - - `ApplyPatch object { type }` + - `ApplyPatch object { type, allowed_callers }` Allows the assistant to create, delete, or update files using unified diffs. @@ -6419,6 +7478,14 @@ Create items in a conversation with the given ID. - `"apply_patch"` + - `allowed_callers: optional array of "direct" or "programmatic"` + + The tool invocation context(s). + + - `"direct"` + + - `"programmatic"` + - `type: "tool_search_output"` The item type. Always `tool_search_output`. @@ -6459,11 +7526,11 @@ Create items in a conversation with the given ID. - `"developer"` - - `tools: array of object { name, parameters, strict, 3 more } or object { type, vector_store_ids, filters, 2 more } or object { type } or 12 more` + - `tools: array of object { name, parameters, strict, 5 more } or object { type, vector_store_ids, filters, 2 more } or object { type } or 13 more` A list of additional tools made available at this item. - - `Function object { name, parameters, strict, 3 more }` + - `Function object { name, parameters, strict, 5 more }` Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). @@ -6477,7 +7544,7 @@ Create items in a conversation with the given ID. - `strict: boolean` - Whether to enforce strict parameter validation. Default `true`. + Whether strict parameter validation is enforced for this function tool. - `type: "function"` @@ -6485,6 +7552,14 @@ Create items in a conversation with the given ID. - `"function"` + - `allowed_callers: optional array of "direct" or "programmatic"` + + The tool invocation context(s). + + - `"direct"` + + - `"programmatic"` + - `defer_loading: optional boolean` Whether this function is deferred and loaded via tool search. @@ -6493,6 +7568,10 @@ Create items in a conversation with the given ID. 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). @@ -6596,7 +7675,7 @@ Create items in a conversation with the given ID. - `WebSearch object { type, filters, search_context_size, user_location }` Search the Internet for sources related to the prompt. Learn more about the - [web search tool](/docs/guides/tools-web-search). + [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - `type: "web_search" or "web_search_2025_08_26"` @@ -6653,10 +7732,10 @@ Create items in a conversation with the given ID. - `"approximate"` - - `Mcp object { server_label, type, allowed_tools, 8 more }` + - `Mcp object { server_label, type, allowed_callers, 9 more }` Give the model access to additional tools via remote Model Context Protocol - (MCP) servers. [Learn more about MCP](/docs/guides/tools-remote-mcp). + (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). - `server_label: string` @@ -6668,7 +7747,15 @@ Create items in a conversation with the given ID. - `"mcp"` - - `allowed_tools: optional array of string or object { read_only, tool_names }` + - `allowed_callers: optional array of "direct" or "programmatic"` + + The tool invocation context(s). + + - `"direct"` + + - `"programmatic"` + + - `allowed_tools: optional array of string or object { read_only, tool_names }` List of allowed tool names or a filter object. @@ -6700,7 +7787,7 @@ Create items in a conversation with the given ID. Identifier for service connectors, like those available in ChatGPT. One of `server_url`, `connector_id`, or `tunnel_id` must be provided. Learn more - about service connectors [here](/docs/guides/tools-remote-mcp#connectors). + about service connectors [here](https://platform.openai.com/docs/guides/tools-remote-mcp#connectors). Currently supported `connector_id` values are: @@ -6800,7 +7887,7 @@ Create items in a conversation with the given ID. The Secure MCP Tunnel ID to use instead of a direct server URL. One of `server_url`, `connector_id`, or `tunnel_id` must be provided. - - `CodeInterpreter object { container, type }` + - `CodeInterpreter object { container, type, allowed_callers }` A tool that runs Python code to help generate a response to a prompt. @@ -6854,6 +7941,22 @@ Create items in a conversation with the given ID. - `"code_interpreter"` + - `allowed_callers: optional array of "direct" or "programmatic"` + + The tool invocation context(s). + + - `"direct"` + + - `"programmatic"` + + - `ProgrammaticToolCalling object { type }` + + - `type: "programmatic_tool_calling"` + + The type of the tool. Always `programmatic_tool_calling`. + + - `"programmatic_tool_calling"` + - `ImageGeneration object { type, action, background, 9 more }` A tool that generates images using the GPT image models. @@ -6876,8 +7979,19 @@ Create items in a conversation with the given ID. - `background: optional "transparent" or "opaque" or "auto"` - Background type for the generated image. One of `transparent`, - `opaque`, or `auto`. Default: `auto`. + Allows to set transparency for the background of the generated image(s). + This parameter is only supported for GPT image models that support + transparent backgrounds. Must be one of `transparent`, `opaque`, or + `auto` (default value). When `auto` is used, the model will + automatically determine the best background for the image. + + `gpt-image-2` and `gpt-image-2-2026-04-21` do not support + transparent backgrounds. Requests with `background` set to + `transparent` will return an error for these models; use `opaque` or + `auto` instead. + + If `transparent`, the output format needs to support transparency, + so it should be set to either `png` (default value) or `webp`. - `"transparent"` @@ -6906,13 +8020,13 @@ Create items in a conversation with the given ID. Base64-encoded mask image. - - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` + - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-2" or 3 more` The image generation model to use. Default: `gpt-image-1`. - `string` - - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` + - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-2" or 3 more` The image generation model to use. Default: `gpt-image-1`. @@ -6920,8 +8034,14 @@ Create items in a conversation with the given ID. - `"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`. @@ -6990,7 +8110,7 @@ Create items in a conversation with the given ID. - `"local_shell"` - - `Shell object { type, environment }` + - `Shell object { type, allowed_callers, environment }` A tool that allows the model to execute shell commands. @@ -7000,6 +8120,14 @@ Create items in a conversation with the given ID. - `"shell"` + - `allowed_callers: optional array of "direct" or "programmatic"` + + The tool invocation context(s). + + - `"direct"` + + - `"programmatic"` + - `environment: optional ContainerAuto or LocalEnvironment or ContainerReference` - `ContainerAuto object { type, file_ids, memory_limit, 2 more }` @@ -7008,9 +8136,9 @@ Create items in a conversation with the given ID. - `ContainerReference object { container_id, type }` - - `Custom object { name, type, defer_loading, 2 more }` + - `Custom object { name, type, allowed_callers, 3 more }` - A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) - `name: string` @@ -7022,6 +8150,14 @@ Create items in a conversation with the given ID. - `"custom"` + - `allowed_callers: optional array of "direct" or "programmatic"` + + The tool invocation context(s). + + - `"direct"` + + - `"programmatic"` + - `defer_loading: optional boolean` Whether this tool should be deferred and discovered via tool search. @@ -7046,11 +8182,11 @@ Create items in a conversation with the given ID. The namespace name used in tool calls (for example, `crm`). - - `tools: array of object { name, type, defer_loading, 3 more } or object { name, type, defer_loading, 2 more }` + - `tools: array of object { name, type, allowed_callers, 5 more } or object { name, type, allowed_callers, 3 more }` The function/custom tools available inside this namespace. - - `Function object { name, type, defer_loading, 3 more }` + - `Function object { name, type, allowed_callers, 5 more }` - `name: string` @@ -7058,19 +8194,33 @@ Create items in a conversation with the given ID. - `"function"` + - `allowed_callers: optional array of "direct" or "programmatic"` + + The tool invocation context(s). + + - `"direct"` + + - `"programmatic"` + - `defer_loading: optional boolean` Whether this function should be deferred and discovered via tool search. - `description: optional string` + - `output_schema: optional map[unknown]` + + A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. + - `parameters: optional unknown` - `strict: optional boolean` - - `Custom object { name, type, defer_loading, 2 more }` + Whether to enforce strict parameter validation. If omitted, Responses attempts to use strict validation when the schema is compatible, and falls back to non-strict validation otherwise. - A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) + - `Custom object { name, type, allowed_callers, 3 more }` + + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) - `name: string` @@ -7082,6 +8232,14 @@ Create items in a conversation with the given ID. - `"custom"` + - `allowed_callers: optional array of "direct" or "programmatic"` + + The tool invocation context(s). + + - `"direct"` + + - `"programmatic"` + - `defer_loading: optional boolean` Whether this tool should be deferred and discovered via tool search. @@ -7180,7 +8338,7 @@ Create items in a conversation with the given ID. The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - - `ApplyPatch object { type }` + - `ApplyPatch object { type, allowed_callers }` Allows the assistant to create, delete, or update files using unified diffs. @@ -7190,6 +8348,14 @@ Create items in a conversation with the given ID. - `"apply_patch"` + - `allowed_callers: optional array of "direct" or "programmatic"` + + The tool invocation context(s). + + - `"direct"` + + - `"programmatic"` + - `type: "additional_tools"` The item type. Always `additional_tools`. @@ -7205,13 +8371,13 @@ Create items in a conversation with the given ID. A description of the chain of thought used by a reasoning model while generating a response. Be sure to include these items in your `input` to the Responses API for subsequent turns of a conversation if you are manually - [managing context](/docs/guides/conversation-state). + [managing context](https://platform.openai.com/docs/guides/conversation-state). - `id: string` The unique identifier of the reasoning content. - - `summary: array of SummaryTextContent` + - `summary: array of object { text, type }` Reasoning summary content. @@ -7263,7 +8429,7 @@ Create items in a conversation with the given ID. - `Compaction object { encrypted_content, type, id }` - A compaction item generated by the [`v1/responses/compact` API](/docs/api-reference/responses/compact). + A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). - `encrypted_content: string` @@ -7464,7 +8630,7 @@ Create items in a conversation with the given ID. - `"incomplete"` - - `ShellCall object { action, call_id, type, 3 more }` + - `ShellCall object { action, call_id, type, 4 more }` A tool representing a request to execute one or more shell commands. @@ -7498,6 +8664,30 @@ Create items in a conversation with the given ID. The unique ID of the shell tool call. Populated when this item is returned via API. + - `caller: optional object { type } or object { caller_id, type }` + + The execution context that produced this tool call. + + - `Direct object { type }` + + - `type: "direct"` + + The caller type. Always `direct`. + + - `"direct"` + + - `Program object { caller_id, type }` + + - `caller_id: string` + + The call ID of the program item that produced this tool call. + + - `type: "program"` + + The caller type. Always `program`. + + - `"program"` + - `environment: optional LocalEnvironment or ContainerReference` The environment to execute the shell commands in. @@ -7516,7 +8706,7 @@ Create items in a conversation with the given ID. - `"incomplete"` - - `ShellCallOutput object { call_id, output, type, 3 more }` + - `ShellCallOutput object { call_id, output, type, 4 more }` The streamed output items emitted by a shell tool call. @@ -7574,6 +8764,30 @@ Create items in a conversation with the given ID. The unique ID of the shell tool call output. Populated when this item is returned via API. + - `caller: optional object { type } or object { caller_id, type }` + + The execution context that produced this tool call. + + - `Direct object { type }` + + - `type: "direct"` + + The caller type. Always `direct`. + + - `"direct"` + + - `Program object { caller_id, type }` + + - `caller_id: string` + + The call ID of the program item that produced this tool call. + + - `type: "program"` + + The caller type. Always `program`. + + - `"program"` + - `max_output_length: optional number` The maximum number of UTF-8 characters captured for this shell call's combined output. @@ -7588,7 +8802,7 @@ Create items in a conversation with the given ID. - `"incomplete"` - - `ApplyPatchCall object { call_id, operation, status, 2 more }` + - `ApplyPatchCall object { call_id, operation, status, 3 more }` A tool call representing a request to create, delete, or update files using diff patches. @@ -7668,7 +8882,31 @@ Create items in a conversation with the given ID. The unique ID of the apply patch tool call. Populated when this item is returned via API. - - `ApplyPatchCallOutput object { call_id, status, type, 2 more }` + - `caller: optional object { type } or object { caller_id, type }` + + The execution context that produced this tool call. + + - `Direct object { type }` + + - `type: "direct"` + + The caller type. Always `direct`. + + - `"direct"` + + - `Program object { caller_id, type }` + + - `caller_id: string` + + The call ID of the program item that produced this tool call. + + - `type: "program"` + + The caller type. Always `program`. + + - `"program"` + + - `ApplyPatchCallOutput object { call_id, status, type, 3 more }` The streamed output emitted by an apply patch tool call. @@ -7694,6 +8932,30 @@ Create items in a conversation with the given ID. The unique ID of the apply patch tool call output. Populated when this item is returned via API. + - `caller: optional object { type } or object { caller_id, type }` + + The execution context that produced this tool call. + + - `Direct object { type }` + + - `type: "direct"` + + The caller type. Always `direct`. + + - `"direct"` + + - `Program object { caller_id, type }` + + - `caller_id: string` + + The call ID of the program item that produced this tool call. + + - `type: "program"` + + The caller type. Always `program`. + + - `"program"` + - `output: optional string` Optional human-readable log text from the apply patch tool (e.g., patch results or errors). @@ -7845,7 +9107,7 @@ Create items in a conversation with the given ID. - `"failed"` - - `CustomToolCallOutput object { call_id, output, type, id }` + - `CustomToolCallOutput object { call_id, output, type, 2 more }` The output of a custom tool call from your code, being sent back to the model. @@ -7866,15 +9128,15 @@ Create items in a conversation with the given ID. Text, image, or file output of the custom tool call. - - `ResponseInputText object { text, type }` + - `ResponseInputText object { text, type, prompt_cache_breakpoint }` A text input to the model. - - `ResponseInputImage object { detail, type, file_id, image_url }` + - `ResponseInputImage object { detail, type, file_id, 2 more }` - An image input to the model. Learn about [image inputs](/docs/guides/vision). + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - `ResponseInputFile object { type, detail, file_data, 3 more }` + - `ResponseInputFile object { type, detail, file_data, 4 more }` A file input to the model. @@ -7888,7 +9150,31 @@ Create items in a conversation with the given ID. The unique ID of the custom tool call output in the OpenAI platform. - - `CustomToolCall object { call_id, input, name, 3 more }` + - `caller: optional object { type } or object { caller_id, type }` + + The execution context that produced this tool call. + + - `Direct object { type }` + + - `type: "direct"` + + The caller type. Always `direct`. + + - `"direct"` + + - `Program object { caller_id, type }` + + - `caller_id: string` + + The call ID of the program item that produced this tool call. + + - `type: "program"` + + The caller type. Always `program`. + + - `"program"` + + - `CustomToolCall object { call_id, input, name, 4 more }` A call to a custom tool created by the model. @@ -7914,6 +9200,26 @@ Create items in a conversation with the given ID. The unique ID of the custom tool call in the OpenAI platform. + - `caller: optional object { type } or object { caller_id, type }` + + The execution context that produced this tool call. + + - `Direct object { type }` + + - `type: "direct"` + + - `"direct"` + + - `Program object { caller_id, type }` + + - `caller_id: string` + + The call ID of the program item that produced this tool call. + + - `type: "program"` + + - `"program"` + - `namespace: optional string` The namespace of the custom tool being called. @@ -7942,6 +9248,58 @@ Create items in a conversation with the given ID. - `"item_reference"` + - `Program object { id, call_id, code, 2 more }` + + - `id: string` + + The unique ID of this program item. + + - `call_id: string` + + The stable call ID of the program item. + + - `code: string` + + The JavaScript source executed by programmatic tool calling. + + - `fingerprint: string` + + Opaque program replay fingerprint that must be round-tripped. + + - `type: "program"` + + The item type. Always `program`. + + - `"program"` + + - `ProgramOutput object { id, call_id, result, 2 more }` + + - `id: string` + + The unique ID of this program output item. + + - `call_id: string` + + The call ID of the program item. + + - `result: string` + + The result produced by the program item. + + - `status: "completed" or "incomplete"` + + The terminal status of the program output. + + - `"completed"` + + - `"incomplete"` + + - `type: "program_output"` + + The item type. Always `program_output`. + + - `"program_output"` + ### Returns - `ConversationItemList object { data, first_id, has_more, 2 more }` @@ -7964,7 +9322,7 @@ Create items in a conversation with the given ID. The content of the message - - `ResponseInputText object { text, type }` + - `ResponseInputText object { text, type, prompt_cache_breakpoint }` A text input to the model. @@ -7978,7 +9336,17 @@ Create items in a conversation with the given ID. - `"input_text"` - - `ResponseOutputText object { annotations, logprobs, text, type }` + - `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 }` A text output from the model. @@ -8082,15 +9450,17 @@ Create items in a conversation with the given ID. - `"file_path"` - - `logprobs: array of object { token, bytes, logprob, top_logprobs }` + - `text: string` - - `token: string` + The text output from the model. - - `bytes: array of number` + - `type: "output_text"` - - `logprob: number` + The type of the output text. Always `output_text`. - - `top_logprobs: array of object { token, bytes, logprob }` + - `"output_text"` + + - `logprobs: optional array of object { token, bytes, logprob, top_logprobs }` - `token: string` @@ -8098,15 +9468,13 @@ Create items in a conversation with the given ID. - `logprob: number` - - `text: string` - - The text output from the model. + - `top_logprobs: array of object { token, bytes, logprob }` - - `type: "output_text"` + - `token: string` - The type of the output text. Always `output_text`. + - `bytes: array of number` - - `"output_text"` + - `logprob: number` - `TextContent object { text, type }` @@ -8160,9 +9528,9 @@ Create items in a conversation with the given ID. - `"refusal"` - - `ResponseInputImage object { detail, type, file_id, image_url }` + - `ResponseInputImage object { detail, type, file_id, 2 more }` - An image input to the model. Learn about [image inputs](/docs/guides/vision). + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - `detail: "low" or "high" or "auto" or "original"` @@ -8190,7 +9558,17 @@ Create items in a conversation with the given ID. The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - - `ComputerScreenshotContent object { detail, file_id, image_url, type }` + - `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"` + + - `ComputerScreenshotContent object { detail, file_id, image_url, 2 more }` A screenshot of a computer. @@ -8220,7 +9598,17 @@ Create items in a conversation with the given ID. - `"computer_screenshot"` - - `ResponseInputFile object { type, detail, file_data, 3 more }` + - `prompt_cache_breakpoint: optional object { mode }` + + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + + - `mode: "explicit"` + + The breakpoint mode. Always `explicit`. + + - `"explicit"` + + - `ResponseInputFile object { type, detail, file_data, 4 more }` A file input to the model. @@ -8230,9 +9618,11 @@ Create items in a conversation with the given ID. - `"input_file"` - - `detail: optional "low" or "high"` + - `detail: optional "auto" or "low" or "high"` - The detail level of the file to be sent to the model. Use `low` for the default rendering behavior, or `high` to render the file at higher quality. Defaults to `low`. + The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. + + - `"auto"` - `"low"` @@ -8254,6 +9644,16 @@ Create items in a conversation with the given ID. The name of the file to be sent to the model. + - `prompt_cache_breakpoint: optional object { mode }` + + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + + - `mode: "explicit"` + + The breakpoint mode. Always `explicit`. + + - `"explicit"` + - `role: "unknown" or "user" or "assistant" or 5 more` The role of the message. One of `unknown`, `user`, `assistant`, `system`, `critic`, `discriminator`, `developer`, or `tool`. @@ -8298,7 +9698,7 @@ Create items in a conversation with the given ID. - `"final_answer"` - - `FunctionCall object { id, arguments, call_id, 5 more }` + - `FunctionCall object { id, arguments, call_id, 6 more }` - `id: string` @@ -8333,6 +9733,26 @@ Create items in a conversation with the given ID. - `"function_call"` + - `caller: optional object { type } or object { caller_id, type }` + + The execution context that produced this tool call. + + - `Direct object { type }` + + - `type: "direct"` + + - `"direct"` + + - `Program object { caller_id, type }` + + - `caller_id: string` + + The call ID of the program item that produced this tool call. + + - `type: "program"` + + - `"program"` + - `created_by: optional string` The identifier of the actor that created the item. @@ -8341,7 +9761,7 @@ Create items in a conversation with the given ID. The namespace of the function to run. - - `FunctionCallOutput object { id, call_id, output, 3 more }` + - `FunctionCallOutput object { id, call_id, output, 4 more }` - `id: string` @@ -8364,15 +9784,15 @@ Create items in a conversation with the given ID. Text, image, or file output of the function call. - - `ResponseInputText object { text, type }` + - `ResponseInputText object { text, type, prompt_cache_breakpoint }` A text input to the model. - - `ResponseInputImage object { detail, type, file_id, image_url }` + - `ResponseInputImage object { detail, type, file_id, 2 more }` - An image input to the model. Learn about [image inputs](/docs/guides/vision). + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - `ResponseInputFile object { type, detail, file_data, 3 more }` + - `ResponseInputFile object { type, detail, file_data, 4 more }` A file input to the model. @@ -8393,6 +9813,30 @@ Create items in a conversation with the given ID. - `"function_call_output"` + - `caller: optional object { type } or object { caller_id, type }` + + The execution context that produced this tool call. + + - `Direct object { type }` + + - `type: "direct"` + + The caller type. Always `direct`. + + - `"direct"` + + - `Program object { caller_id, type }` + + - `caller_id: string` + + The call ID of the program item that produced this tool call. + + - `type: "program"` + + The caller type. Always `program`. + + - `"program"` + - `created_by: optional string` The identifier of the actor that created the item. @@ -8400,7 +9844,7 @@ Create items in a conversation with the given ID. - `FileSearchCall object { id, queries, status, 2 more }` The results of a file search tool call. See the - [file search guide](/docs/guides/tools-file-search) for more information. + [file search guide](https://platform.openai.com/docs/guides/tools-file-search) for more information. - `id: string` @@ -8468,7 +9912,7 @@ Create items in a conversation with the given ID. - `WebSearchCall object { id, action, status, type }` The results of a web search tool call. See the - [web search guide](/docs/guides/tools-web-search) for more information. + [web search guide](https://platform.openai.com/docs/guides/tools-web-search) for more information. - `id: string` @@ -8594,7 +10038,7 @@ Create items in a conversation with the given ID. - `ComputerCall object { id, call_id, pending_safety_checks, 4 more }` A tool call to a computer use tool. See the - [computer use guide](/docs/guides/tools-computer-use) for more information. + [computer use guide](https://platform.openai.com/docs/guides/tools-computer-use) for more information. - `id: string` @@ -8637,7 +10081,7 @@ Create items in a conversation with the given ID. - `"computer_call"` - - `action: optional ComputerAction` + - `action: optional object { button, type, x, 2 more } or object { keys, type, x, y } or object { path, type, keys } or 6 more` A click action. @@ -8841,53 +10285,208 @@ Create items in a conversation with the given ID. A click action. - - `DoubleClick object { keys, type, x, y }` + - `button: "left" or "right" or "wheel" or 2 more` - A double click action. + Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. - - `Drag object { path, type, keys }` + - `"left"` - A drag action. + - `"right"` - - `Keypress object { keys, type }` + - `"wheel"` - A collection of keypresses the model would like to perform. + - `"back"` - - `Move object { type, x, y, keys }` + - `"forward"` - A mouse move action. + - `type: "click"` - - `Screenshot object { type }` + Specifies the event type. For a click action, this property is always `click`. - A screenshot action. + - `"click"` - - `Scroll object { scroll_x, scroll_y, type, 3 more }` + - `x: number` - A scroll action. + The x-coordinate where the click occurred. - - `Type object { text, type }` + - `y: number` - An action to type in text. + The y-coordinate where the click occurred. - - `Wait object { type }` + - `keys: optional array of string` - A wait action. + The keys being held while clicking. - - `ComputerCallOutput object { id, call_id, output, 4 more }` + - `DoubleClick object { keys, type, x, y }` - - `id: string` + A double click action. - The unique ID of the computer call tool output. + - `keys: array of string` - - `call_id: string` + The keys being held while double-clicking. - The ID of the computer tool call that produced the output. + - `type: "double_click"` - - `output: ResponseComputerToolCallOutputScreenshot` + Specifies the event type. For a double click action, this property is always set to `double_click`. - A computer screenshot image used with the computer use tool. + - `"double_click"` - - `type: "computer_screenshot"` + - `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 { id, call_id, output, 4 more }` + + - `id: string` + + The unique ID of the computer call tool output. + + - `call_id: string` + + The ID of the computer tool call that produced the output. + + - `output: ResponseComputerToolCallOutputScreenshot` + + A computer screenshot image used with the computer use tool. + + - `type: "computer_screenshot"` Specifies the event type. For a computer screenshot, this property is always set to `computer_screenshot`. @@ -9012,11 +10611,11 @@ Create items in a conversation with the given ID. - `"incomplete"` - - `tools: array of object { name, parameters, strict, 3 more } or object { type, vector_store_ids, filters, 2 more } or object { type } or 12 more` + - `tools: array of object { name, parameters, strict, 5 more } or object { type, vector_store_ids, filters, 2 more } or object { type } or 13 more` The loaded tool definitions returned by tool search. - - `Function object { name, parameters, strict, 3 more }` + - `Function object { name, parameters, strict, 5 more }` Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). @@ -9030,7 +10629,7 @@ Create items in a conversation with the given ID. - `strict: boolean` - Whether to enforce strict parameter validation. Default `true`. + Whether strict parameter validation is enforced for this function tool. - `type: "function"` @@ -9038,6 +10637,14 @@ Create items in a conversation with the given ID. - `"function"` + - `allowed_callers: optional array of "direct" or "programmatic"` + + The tool invocation context(s). + + - `"direct"` + + - `"programmatic"` + - `defer_loading: optional boolean` Whether this function is deferred and loaded via tool search. @@ -9046,6 +10653,10 @@ Create items in a conversation with the given ID. 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). @@ -9216,7 +10827,7 @@ Create items in a conversation with the given ID. - `WebSearch object { type, filters, search_context_size, user_location }` Search the Internet for sources related to the prompt. Learn more about the - [web search tool](/docs/guides/tools-web-search). + [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - `type: "web_search" or "web_search_2025_08_26"` @@ -9273,10 +10884,10 @@ Create items in a conversation with the given ID. - `"approximate"` - - `Mcp object { server_label, type, allowed_tools, 8 more }` + - `Mcp object { server_label, type, allowed_callers, 9 more }` Give the model access to additional tools via remote Model Context Protocol - (MCP) servers. [Learn more about MCP](/docs/guides/tools-remote-mcp). + (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). - `server_label: string` @@ -9288,6 +10899,14 @@ Create items in a conversation with the given ID. - `"mcp"` + - `allowed_callers: optional array of "direct" or "programmatic"` + + The tool invocation context(s). + + - `"direct"` + + - `"programmatic"` + - `allowed_tools: optional array of string or object { read_only, tool_names }` List of allowed tool names or a filter object. @@ -9320,7 +10939,7 @@ Create items in a conversation with the given ID. Identifier for service connectors, like those available in ChatGPT. One of `server_url`, `connector_id`, or `tunnel_id` must be provided. Learn more - about service connectors [here](/docs/guides/tools-remote-mcp#connectors). + about service connectors [here](https://platform.openai.com/docs/guides/tools-remote-mcp#connectors). Currently supported `connector_id` values are: @@ -9420,7 +11039,7 @@ Create items in a conversation with the given ID. The Secure MCP Tunnel ID to use instead of a direct server URL. One of `server_url`, `connector_id`, or `tunnel_id` must be provided. - - `CodeInterpreter object { container, type }` + - `CodeInterpreter object { container, type, allowed_callers }` A tool that runs Python code to help generate a response to a prompt. @@ -9506,6 +11125,22 @@ Create items in a conversation with the given ID. - `"code_interpreter"` + - `allowed_callers: optional array of "direct" or "programmatic"` + + The tool invocation context(s). + + - `"direct"` + + - `"programmatic"` + + - `ProgrammaticToolCalling object { type }` + + - `type: "programmatic_tool_calling"` + + The type of the tool. Always `programmatic_tool_calling`. + + - `"programmatic_tool_calling"` + - `ImageGeneration object { type, action, background, 9 more }` A tool that generates images using the GPT image models. @@ -9528,8 +11163,19 @@ Create items in a conversation with the given ID. - `background: optional "transparent" or "opaque" or "auto"` - Background type for the generated image. One of `transparent`, - `opaque`, or `auto`. Default: `auto`. + Allows to set transparency for the background of the generated image(s). + This parameter is only supported for GPT image models that support + transparent backgrounds. Must be one of `transparent`, `opaque`, or + `auto` (default value). When `auto` is used, the model will + automatically determine the best background for the image. + + `gpt-image-2` and `gpt-image-2-2026-04-21` do not support + transparent backgrounds. Requests with `background` set to + `transparent` will return an error for these models; use `opaque` or + `auto` instead. + + If `transparent`, the output format needs to support transparency, + so it should be set to either `png` (default value) or `webp`. - `"transparent"` @@ -9558,13 +11204,13 @@ Create items in a conversation with the given ID. Base64-encoded mask image. - - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` + - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-2" or 3 more` The image generation model to use. Default: `gpt-image-1`. - `string` - - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` + - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-2" or 3 more` The image generation model to use. Default: `gpt-image-1`. @@ -9572,8 +11218,14 @@ Create items in a conversation with the given ID. - `"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`. @@ -9642,7 +11294,7 @@ Create items in a conversation with the given ID. - `"local_shell"` - - `Shell object { type, environment }` + - `Shell object { type, allowed_callers, environment }` A tool that allows the model to execute shell commands. @@ -9652,6 +11304,14 @@ Create items in a conversation with the given ID. - `"shell"` + - `allowed_callers: optional array of "direct" or "programmatic"` + + The tool invocation context(s). + + - `"direct"` + + - `"programmatic"` + - `environment: optional ContainerAuto or LocalEnvironment or ContainerReference` - `ContainerAuto object { type, file_ids, memory_limit, 2 more }` @@ -9778,9 +11438,9 @@ Create items in a conversation with the given ID. - `"container_reference"` - - `Custom object { name, type, defer_loading, 2 more }` + - `Custom object { name, type, allowed_callers, 3 more }` - A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) - `name: string` @@ -9792,6 +11452,14 @@ Create items in a conversation with the given ID. - `"custom"` + - `allowed_callers: optional array of "direct" or "programmatic"` + + The tool invocation context(s). + + - `"direct"` + + - `"programmatic"` + - `defer_loading: optional boolean` Whether this tool should be deferred and discovered via tool search. @@ -9848,11 +11516,11 @@ Create items in a conversation with the given ID. The namespace name used in tool calls (for example, `crm`). - - `tools: array of object { name, type, defer_loading, 3 more } or object { name, type, defer_loading, 2 more }` + - `tools: array of object { name, type, allowed_callers, 5 more } or object { name, type, allowed_callers, 3 more }` The function/custom tools available inside this namespace. - - `Function object { name, type, defer_loading, 3 more }` + - `Function object { name, type, allowed_callers, 5 more }` - `name: string` @@ -9860,19 +11528,33 @@ Create items in a conversation with the given ID. - `"function"` + - `allowed_callers: optional array of "direct" or "programmatic"` + + The tool invocation context(s). + + - `"direct"` + + - `"programmatic"` + - `defer_loading: optional boolean` Whether this function should be deferred and discovered via tool search. - `description: optional string` + - `output_schema: optional map[unknown]` + + A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. + - `parameters: optional unknown` - `strict: optional boolean` - - `Custom object { name, type, defer_loading, 2 more }` + Whether to enforce strict parameter validation. If omitted, Responses attempts to use strict validation when the schema is compatible, and falls back to non-strict validation otherwise. + + - `Custom object { name, type, allowed_callers, 3 more }` - A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) - `name: string` @@ -9884,6 +11566,14 @@ Create items in a conversation with the given ID. - `"custom"` + - `allowed_callers: optional array of "direct" or "programmatic"` + + The tool invocation context(s). + + - `"direct"` + + - `"programmatic"` + - `defer_loading: optional boolean` Whether this tool should be deferred and discovered via tool search. @@ -9982,7 +11672,7 @@ Create items in a conversation with the given ID. The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - - `ApplyPatch object { type }` + - `ApplyPatch object { type, allowed_callers }` Allows the assistant to create, delete, or update files using unified diffs. @@ -9992,6 +11682,14 @@ Create items in a conversation with the given ID. - `"apply_patch"` + - `allowed_callers: optional array of "direct" or "programmatic"` + + The tool invocation context(s). + + - `"direct"` + + - `"programmatic"` + - `type: "tool_search_output"` The type of the item. Always `tool_search_output`. @@ -10028,11 +11726,11 @@ Create items in a conversation with the given ID. - `"tool"` - - `tools: array of object { name, parameters, strict, 3 more } or object { type, vector_store_ids, filters, 2 more } or object { type } or 12 more` + - `tools: array of object { name, parameters, strict, 5 more } or object { type, vector_store_ids, filters, 2 more } or object { type } or 13 more` The additional tool definitions made available at this item. - - `Function object { name, parameters, strict, 3 more }` + - `Function object { name, parameters, strict, 5 more }` Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). @@ -10046,7 +11744,7 @@ Create items in a conversation with the given ID. - `strict: boolean` - Whether to enforce strict parameter validation. Default `true`. + Whether strict parameter validation is enforced for this function tool. - `type: "function"` @@ -10054,6 +11752,14 @@ Create items in a conversation with the given ID. - `"function"` + - `allowed_callers: optional array of "direct" or "programmatic"` + + The tool invocation context(s). + + - `"direct"` + + - `"programmatic"` + - `defer_loading: optional boolean` Whether this function is deferred and loaded via tool search. @@ -10062,6 +11768,10 @@ Create items in a conversation with the given ID. 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). @@ -10165,7 +11875,7 @@ Create items in a conversation with the given ID. - `WebSearch object { type, filters, search_context_size, user_location }` Search the Internet for sources related to the prompt. Learn more about the - [web search tool](/docs/guides/tools-web-search). + [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - `type: "web_search" or "web_search_2025_08_26"` @@ -10222,10 +11932,10 @@ Create items in a conversation with the given ID. - `"approximate"` - - `Mcp object { server_label, type, allowed_tools, 8 more }` + - `Mcp object { server_label, type, allowed_callers, 9 more }` Give the model access to additional tools via remote Model Context Protocol - (MCP) servers. [Learn more about MCP](/docs/guides/tools-remote-mcp). + (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). - `server_label: string` @@ -10237,6 +11947,14 @@ Create items in a conversation with the given ID. - `"mcp"` + - `allowed_callers: optional array of "direct" or "programmatic"` + + The tool invocation context(s). + + - `"direct"` + + - `"programmatic"` + - `allowed_tools: optional array of string or object { read_only, tool_names }` List of allowed tool names or a filter object. @@ -10269,7 +11987,7 @@ Create items in a conversation with the given ID. Identifier for service connectors, like those available in ChatGPT. One of `server_url`, `connector_id`, or `tunnel_id` must be provided. Learn more - about service connectors [here](/docs/guides/tools-remote-mcp#connectors). + about service connectors [here](https://platform.openai.com/docs/guides/tools-remote-mcp#connectors). Currently supported `connector_id` values are: @@ -10369,7 +12087,7 @@ Create items in a conversation with the given ID. The Secure MCP Tunnel ID to use instead of a direct server URL. One of `server_url`, `connector_id`, or `tunnel_id` must be provided. - - `CodeInterpreter object { container, type }` + - `CodeInterpreter object { container, type, allowed_callers }` A tool that runs Python code to help generate a response to a prompt. @@ -10423,6 +12141,22 @@ Create items in a conversation with the given ID. - `"code_interpreter"` + - `allowed_callers: optional array of "direct" or "programmatic"` + + The tool invocation context(s). + + - `"direct"` + + - `"programmatic"` + + - `ProgrammaticToolCalling object { type }` + + - `type: "programmatic_tool_calling"` + + The type of the tool. Always `programmatic_tool_calling`. + + - `"programmatic_tool_calling"` + - `ImageGeneration object { type, action, background, 9 more }` A tool that generates images using the GPT image models. @@ -10445,8 +12179,19 @@ Create items in a conversation with the given ID. - `background: optional "transparent" or "opaque" or "auto"` - Background type for the generated image. One of `transparent`, - `opaque`, or `auto`. Default: `auto`. + Allows to set transparency for the background of the generated image(s). + This parameter is only supported for GPT image models that support + transparent backgrounds. Must be one of `transparent`, `opaque`, or + `auto` (default value). When `auto` is used, the model will + automatically determine the best background for the image. + + `gpt-image-2` and `gpt-image-2-2026-04-21` do not support + transparent backgrounds. Requests with `background` set to + `transparent` will return an error for these models; use `opaque` or + `auto` instead. + + If `transparent`, the output format needs to support transparency, + so it should be set to either `png` (default value) or `webp`. - `"transparent"` @@ -10475,13 +12220,13 @@ Create items in a conversation with the given ID. Base64-encoded mask image. - - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` + - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-2" or 3 more` The image generation model to use. Default: `gpt-image-1`. - `string` - - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` + - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-2" or 3 more` The image generation model to use. Default: `gpt-image-1`. @@ -10489,8 +12234,14 @@ Create items in a conversation with the given ID. - `"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`. @@ -10559,7 +12310,7 @@ Create items in a conversation with the given ID. - `"local_shell"` - - `Shell object { type, environment }` + - `Shell object { type, allowed_callers, environment }` A tool that allows the model to execute shell commands. @@ -10569,6 +12320,14 @@ Create items in a conversation with the given ID. - `"shell"` + - `allowed_callers: optional array of "direct" or "programmatic"` + + The tool invocation context(s). + + - `"direct"` + + - `"programmatic"` + - `environment: optional ContainerAuto or LocalEnvironment or ContainerReference` - `ContainerAuto object { type, file_ids, memory_limit, 2 more }` @@ -10577,9 +12336,9 @@ Create items in a conversation with the given ID. - `ContainerReference object { container_id, type }` - - `Custom object { name, type, defer_loading, 2 more }` + - `Custom object { name, type, allowed_callers, 3 more }` - A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) - `name: string` @@ -10591,6 +12350,14 @@ Create items in a conversation with the given ID. - `"custom"` + - `allowed_callers: optional array of "direct" or "programmatic"` + + The tool invocation context(s). + + - `"direct"` + + - `"programmatic"` + - `defer_loading: optional boolean` Whether this tool should be deferred and discovered via tool search. @@ -10615,11 +12382,11 @@ Create items in a conversation with the given ID. The namespace name used in tool calls (for example, `crm`). - - `tools: array of object { name, type, defer_loading, 3 more } or object { name, type, defer_loading, 2 more }` + - `tools: array of object { name, type, allowed_callers, 5 more } or object { name, type, allowed_callers, 3 more }` The function/custom tools available inside this namespace. - - `Function object { name, type, defer_loading, 3 more }` + - `Function object { name, type, allowed_callers, 5 more }` - `name: string` @@ -10627,19 +12394,33 @@ Create items in a conversation with the given ID. - `"function"` + - `allowed_callers: optional array of "direct" or "programmatic"` + + The tool invocation context(s). + + - `"direct"` + + - `"programmatic"` + - `defer_loading: optional boolean` Whether this function should be deferred and discovered via tool search. - `description: optional string` + - `output_schema: optional map[unknown]` + + A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. + - `parameters: optional unknown` - `strict: optional boolean` - - `Custom object { name, type, defer_loading, 2 more }` + Whether to enforce strict parameter validation. If omitted, Responses attempts to use strict validation when the schema is compatible, and falls back to non-strict validation otherwise. + + - `Custom object { name, type, allowed_callers, 3 more }` - A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) - `name: string` @@ -10651,6 +12432,14 @@ Create items in a conversation with the given ID. - `"custom"` + - `allowed_callers: optional array of "direct" or "programmatic"` + + The tool invocation context(s). + + - `"direct"` + + - `"programmatic"` + - `defer_loading: optional boolean` Whether this tool should be deferred and discovered via tool search. @@ -10749,7 +12538,7 @@ Create items in a conversation with the given ID. The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - - `ApplyPatch object { type }` + - `ApplyPatch object { type, allowed_callers }` Allows the assistant to create, delete, or update files using unified diffs. @@ -10759,6 +12548,14 @@ Create items in a conversation with the given ID. - `"apply_patch"` + - `allowed_callers: optional array of "direct" or "programmatic"` + + The tool invocation context(s). + + - `"direct"` + + - `"programmatic"` + - `type: "additional_tools"` The type of the item. Always `additional_tools`. @@ -10770,13 +12567,13 @@ Create items in a conversation with the given ID. A description of the chain of thought used by a reasoning model while generating a response. Be sure to include these items in your `input` to the Responses API for subsequent turns of a conversation if you are manually - [managing context](/docs/guides/conversation-state). + [managing context](https://platform.openai.com/docs/guides/conversation-state). - `id: string` The unique identifier of the reasoning content. - - `summary: array of SummaryTextContent` + - `summary: array of object { text, type }` Reasoning summary content. @@ -10788,6 +12585,8 @@ Create items in a conversation with the given ID. The type of the object. Always `summary_text`. + - `"summary_text"` + - `type: "reasoning"` The type of the object. Always `reasoning`. @@ -10824,17 +12623,69 @@ Create items in a conversation with the given ID. - `"incomplete"` - - `Compaction object { id, encrypted_content, type, created_by }` - - A compaction item generated by the [`v1/responses/compact` API](/docs/api-reference/responses/compact). + - `Program object { id, call_id, code, 2 more }` - `id: string` - The unique ID of the compaction item. + The unique ID of the program item. - - `encrypted_content: string` + - `call_id: string` - The encrypted content that was produced by compaction. + The stable call ID of the program item. + + - `code: string` + + The JavaScript source executed by programmatic tool calling. + + - `fingerprint: string` + + Opaque program replay fingerprint that must be round-tripped. + + - `type: "program"` + + The type of the item. Always `program`. + + - `"program"` + + - `ProgramOutput object { id, call_id, result, 2 more }` + + - `id: string` + + The unique ID of the program output item. + + - `call_id: string` + + The call ID of the program item. + + - `result: string` + + The result produced by the program item. + + - `status: "completed" or "incomplete"` + + The terminal status of the program output item. + + - `"completed"` + + - `"incomplete"` + + - `type: "program_output"` + + The type of the item. Always `program_output`. + + - `"program_output"` + + - `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). + + - `id: string` + + The unique ID of the compaction item. + + - `encrypted_content: string` + + The encrypted content that was produced by compaction. - `type: "compaction"` @@ -11001,7 +12852,7 @@ Create items in a conversation with the given ID. - `"incomplete"` - - `ShellCall object { id, action, call_id, 4 more }` + - `ShellCall object { id, action, call_id, 5 more }` A tool call that executes one or more shell commands in a managed environment. @@ -11069,11 +12920,31 @@ Create items in a conversation with the given ID. - `"shell_call"` + - `caller: optional object { type } or object { caller_id, type }` + + The execution context that produced this tool call. + + - `Direct object { type }` + + - `type: "direct"` + + - `"direct"` + + - `Program object { caller_id, type }` + + - `caller_id: string` + + The call ID of the program item that produced this tool call. + + - `type: "program"` + + - `"program"` + - `created_by: optional string` The ID of the entity that created this tool call. - - `ShellCallOutput object { id, call_id, max_output_length, 4 more }` + - `ShellCallOutput object { id, call_id, max_output_length, 5 more }` The output of a shell tool call that was emitted. @@ -11149,11 +13020,31 @@ Create items in a conversation with the given ID. - `"shell_call_output"` + - `caller: optional object { type } or object { caller_id, type }` + + The execution context that produced this tool call. + + - `Direct object { type }` + + - `type: "direct"` + + - `"direct"` + + - `Program object { caller_id, type }` + + - `caller_id: string` + + The call ID of the program item that produced this tool call. + + - `type: "program"` + + - `"program"` + - `created_by: optional string` The identifier of the actor that created the item. - - `ApplyPatchCall object { id, call_id, operation, 3 more }` + - `ApplyPatchCall object { id, call_id, operation, 4 more }` A tool call that applies file diffs by creating, deleting, or updating files. @@ -11233,11 +13124,31 @@ Create items in a conversation with the given ID. - `"apply_patch_call"` + - `caller: optional object { type } or object { caller_id, type }` + + The execution context that produced this tool call. + + - `Direct object { type }` + + - `type: "direct"` + + - `"direct"` + + - `Program object { caller_id, type }` + + - `caller_id: string` + + The call ID of the program item that produced this tool call. + + - `type: "program"` + + - `"program"` + - `created_by: optional string` The ID of the entity that created this tool call. - - `ApplyPatchCallOutput object { id, call_id, status, 3 more }` + - `ApplyPatchCallOutput object { id, call_id, status, 4 more }` The output emitted by an apply patch tool call. @@ -11263,6 +13174,26 @@ Create items in a conversation with the given ID. - `"apply_patch_call_output"` + - `caller: optional object { type } or object { caller_id, type }` + + The execution context that produced this tool call. + + - `Direct object { type }` + + - `type: "direct"` + + - `"direct"` + + - `Program object { caller_id, type }` + + - `caller_id: string` + + The call ID of the program item that produced this tool call. + + - `type: "program"` + + - `"program"` + - `created_by: optional string` The ID of the entity that created this tool call output. @@ -11418,7 +13349,7 @@ Create items in a conversation with the given ID. - `"failed"` - - `CustomToolCall object { call_id, input, name, 3 more }` + - `CustomToolCall object { call_id, input, name, 4 more }` A call to a custom tool created by the model. @@ -11444,11 +13375,31 @@ Create items in a conversation with the given ID. The unique ID of the custom tool call in the OpenAI platform. + - `caller: optional object { type } or object { caller_id, type }` + + The execution context that produced this tool call. + + - `Direct object { type }` + + - `type: "direct"` + + - `"direct"` + + - `Program object { caller_id, type }` + + - `caller_id: string` + + The call ID of the program item that produced this tool call. + + - `type: "program"` + + - `"program"` + - `namespace: optional string` The namespace of the custom tool being called. - - `CustomToolCallOutput object { call_id, output, type, id }` + - `CustomToolCallOutput object { call_id, output, type, 2 more }` The output of a custom tool call from your code, being sent back to the model. @@ -11469,15 +13420,15 @@ Create items in a conversation with the given ID. Text, image, or file output of the custom tool call. - - `ResponseInputText object { text, type }` + - `ResponseInputText object { text, type, prompt_cache_breakpoint }` A text input to the model. - - `ResponseInputImage object { detail, type, file_id, image_url }` + - `ResponseInputImage object { detail, type, file_id, 2 more }` - An image input to the model. Learn about [image inputs](/docs/guides/vision). + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - `ResponseInputFile object { type, detail, file_data, 3 more }` + - `ResponseInputFile object { type, detail, file_data, 4 more }` A file input to the model. @@ -11491,6 +13442,30 @@ Create items in a conversation with the given ID. 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. + + - `Direct object { type }` + + - `type: "direct"` + + The caller type. Always `direct`. + + - `"direct"` + + - `Program object { caller_id, type }` + + - `caller_id: string` + + The call ID of the program item that produced this tool call. + + - `type: "program"` + + The caller type. Always `program`. + + - `"program"` + - `first_id: string` The ID of the first item in the list. @@ -11536,7 +13511,10 @@ curl https://api.openai.com/v1/conversations/$CONVERSATION_ID/items \ "content": [ { "text": "text", - "type": "input_text" + "type": "input_text", + "prompt_cache_breakpoint": { + "mode": "explicit" + } } ], "role": "unknown", @@ -11613,7 +13591,7 @@ curl https://api.openai.com/v1/conversations/conv_123/items \ **get** `/conversations/{conversation_id}/items` -List all items for a conversation with the given ID. +List items ### Path Parameters @@ -11691,7 +13669,7 @@ List all items for a conversation with the given ID. The content of the message - - `ResponseInputText object { text, type }` + - `ResponseInputText object { text, type, prompt_cache_breakpoint }` A text input to the model. @@ -11705,7 +13683,17 @@ List all items for a conversation with the given ID. - `"input_text"` - - `ResponseOutputText object { annotations, logprobs, text, type }` + - `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 }` A text output from the model. @@ -11809,15 +13797,17 @@ List all items for a conversation with the given ID. - `"file_path"` - - `logprobs: array of object { token, bytes, logprob, top_logprobs }` + - `text: string` - - `token: string` + The text output from the model. - - `bytes: array of number` + - `type: "output_text"` - - `logprob: number` + The type of the output text. Always `output_text`. - - `top_logprobs: array of object { token, bytes, logprob }` + - `"output_text"` + + - `logprobs: optional array of object { token, bytes, logprob, top_logprobs }` - `token: string` @@ -11825,15 +13815,13 @@ List all items for a conversation with the given ID. - `logprob: number` - - `text: string` - - The text output from the model. + - `top_logprobs: array of object { token, bytes, logprob }` - - `type: "output_text"` + - `token: string` - The type of the output text. Always `output_text`. + - `bytes: array of number` - - `"output_text"` + - `logprob: number` - `TextContent object { text, type }` @@ -11887,9 +13875,9 @@ List all items for a conversation with the given ID. - `"refusal"` - - `ResponseInputImage object { detail, type, file_id, image_url }` + - `ResponseInputImage object { detail, type, file_id, 2 more }` - An image input to the model. Learn about [image inputs](/docs/guides/vision). + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - `detail: "low" or "high" or "auto" or "original"` @@ -11917,7 +13905,17 @@ List all items for a conversation with the given ID. The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - - `ComputerScreenshotContent object { detail, file_id, image_url, type }` + - `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"` + + - `ComputerScreenshotContent object { detail, file_id, image_url, 2 more }` A screenshot of a computer. @@ -11947,7 +13945,17 @@ List all items for a conversation with the given ID. - `"computer_screenshot"` - - `ResponseInputFile object { type, detail, file_data, 3 more }` + - `prompt_cache_breakpoint: optional object { mode }` + + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + + - `mode: "explicit"` + + The breakpoint mode. Always `explicit`. + + - `"explicit"` + + - `ResponseInputFile object { type, detail, file_data, 4 more }` A file input to the model. @@ -11957,9 +13965,11 @@ List all items for a conversation with the given ID. - `"input_file"` - - `detail: optional "low" or "high"` + - `detail: optional "auto" or "low" or "high"` - The detail level of the file to be sent to the model. Use `low` for the default rendering behavior, or `high` to render the file at higher quality. Defaults to `low`. + The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. + + - `"auto"` - `"low"` @@ -11981,6 +13991,16 @@ List all items for a conversation with the given ID. The name of the file to be sent to the model. + - `prompt_cache_breakpoint: optional object { mode }` + + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + + - `mode: "explicit"` + + The breakpoint mode. Always `explicit`. + + - `"explicit"` + - `role: "unknown" or "user" or "assistant" or 5 more` The role of the message. One of `unknown`, `user`, `assistant`, `system`, `critic`, `discriminator`, `developer`, or `tool`. @@ -12025,7 +14045,7 @@ List all items for a conversation with the given ID. - `"final_answer"` - - `FunctionCall object { id, arguments, call_id, 5 more }` + - `FunctionCall object { id, arguments, call_id, 6 more }` - `id: string` @@ -12060,6 +14080,26 @@ List all items for a conversation with the given ID. - `"function_call"` + - `caller: optional object { type } or object { caller_id, type }` + + The execution context that produced this tool call. + + - `Direct object { type }` + + - `type: "direct"` + + - `"direct"` + + - `Program object { caller_id, type }` + + - `caller_id: string` + + The call ID of the program item that produced this tool call. + + - `type: "program"` + + - `"program"` + - `created_by: optional string` The identifier of the actor that created the item. @@ -12068,7 +14108,7 @@ List all items for a conversation with the given ID. The namespace of the function to run. - - `FunctionCallOutput object { id, call_id, output, 3 more }` + - `FunctionCallOutput object { id, call_id, output, 4 more }` - `id: string` @@ -12091,15 +14131,15 @@ List all items for a conversation with the given ID. Text, image, or file output of the function call. - - `ResponseInputText object { text, type }` + - `ResponseInputText object { text, type, prompt_cache_breakpoint }` A text input to the model. - - `ResponseInputImage object { detail, type, file_id, image_url }` + - `ResponseInputImage object { detail, type, file_id, 2 more }` - An image input to the model. Learn about [image inputs](/docs/guides/vision). + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - `ResponseInputFile object { type, detail, file_data, 3 more }` + - `ResponseInputFile object { type, detail, file_data, 4 more }` A file input to the model. @@ -12120,6 +14160,30 @@ List all items for a conversation with the given ID. - `"function_call_output"` + - `caller: optional object { type } or object { caller_id, type }` + + The execution context that produced this tool call. + + - `Direct object { type }` + + - `type: "direct"` + + The caller type. Always `direct`. + + - `"direct"` + + - `Program object { caller_id, type }` + + - `caller_id: string` + + The call ID of the program item that produced this tool call. + + - `type: "program"` + + The caller type. Always `program`. + + - `"program"` + - `created_by: optional string` The identifier of the actor that created the item. @@ -12127,7 +14191,7 @@ List all items for a conversation with the given ID. - `FileSearchCall object { id, queries, status, 2 more }` The results of a file search tool call. See the - [file search guide](/docs/guides/tools-file-search) for more information. + [file search guide](https://platform.openai.com/docs/guides/tools-file-search) for more information. - `id: string` @@ -12195,7 +14259,7 @@ List all items for a conversation with the given ID. - `WebSearchCall object { id, action, status, type }` The results of a web search tool call. See the - [web search guide](/docs/guides/tools-web-search) for more information. + [web search guide](https://platform.openai.com/docs/guides/tools-web-search) for more information. - `id: string` @@ -12321,7 +14385,7 @@ List all items for a conversation with the given ID. - `ComputerCall object { id, call_id, pending_safety_checks, 4 more }` A tool call to a computer use tool. See the - [computer use guide](/docs/guides/tools-computer-use) for more information. + [computer use guide](https://platform.openai.com/docs/guides/tools-computer-use) for more information. - `id: string` @@ -12364,7 +14428,7 @@ List all items for a conversation with the given ID. - `"computer_call"` - - `action: optional ComputerAction` + - `action: optional object { button, type, x, 2 more } or object { keys, type, x, y } or object { path, type, keys } or 6 more` A click action. @@ -12568,92 +14632,247 @@ List all items for a conversation with the given ID. A click action. - - `DoubleClick object { keys, type, x, y }` + - `button: "left" or "right" or "wheel" or 2 more` - A double click action. + Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. - - `Drag object { path, type, keys }` + - `"left"` - A drag action. + - `"right"` - - `Keypress object { keys, type }` + - `"wheel"` - A collection of keypresses the model would like to perform. + - `"back"` - - `Move object { type, x, y, keys }` + - `"forward"` - A mouse move action. + - `type: "click"` - - `Screenshot object { type }` + Specifies the event type. For a click action, this property is always `click`. - A screenshot action. + - `"click"` - - `Scroll object { scroll_x, scroll_y, type, 3 more }` + - `x: number` - A scroll action. + The x-coordinate where the click occurred. - - `Type object { text, type }` + - `y: number` - An action to type in text. + The y-coordinate where the click occurred. - - `Wait object { type }` + - `keys: optional array of string` - A wait action. + The keys being held while clicking. - - `ComputerCallOutput object { id, call_id, output, 4 more }` + - `DoubleClick object { keys, type, x, y }` - - `id: string` + A double click action. - The unique ID of the computer call tool output. + - `keys: array of string` - - `call_id: string` + The keys being held while double-clicking. - The ID of the computer tool call that produced the output. + - `type: "double_click"` - - `output: ResponseComputerToolCallOutputScreenshot` + Specifies the event type. For a double click action, this property is always set to `double_click`. - A computer screenshot image used with the computer use tool. + - `"double_click"` - - `type: "computer_screenshot"` + - `x: number` - Specifies the event type. For a computer screenshot, this property is - always set to `computer_screenshot`. + The x-coordinate where the double click occurred. - - `"computer_screenshot"` + - `y: number` - - `file_id: optional string` + The y-coordinate where the double click occurred. - The identifier of an uploaded file that contains the screenshot. + - `Drag object { path, type, keys }` - - `image_url: optional string` + A drag action. - The URL of the screenshot image. + - `path: array of object { x, y }` - - `status: "completed" or "incomplete" or "failed" or "in_progress"` + An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg - The status of the message input. One of `in_progress`, `completed`, or - `incomplete`. Populated when input items are returned via API. + ``` + [ + { x: 100, y: 200 }, + { x: 200, y: 300 } + ] + ``` - - `"completed"` + - `x: number` - - `"incomplete"` + The x-coordinate. - - `"failed"` + - `y: number` - - `"in_progress"` + The y-coordinate. - - `type: "computer_call_output"` + - `type: "drag"` - The type of the computer tool call output. Always `computer_call_output`. + Specifies the event type. For a drag action, this property is always set to `drag`. - - `"computer_call_output"` + - `"drag"` - - `acknowledged_safety_checks: optional array of object { id, code, message }` + - `keys: optional array of string` - The safety checks reported by the API that have been acknowledged by the - developer. + The keys being held while dragging the mouse. - - `id: string` + - `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 { id, call_id, output, 4 more }` + + - `id: string` + + The unique ID of the computer call tool output. + + - `call_id: string` + + The ID of the computer tool call that produced the output. + + - `output: ResponseComputerToolCallOutputScreenshot` + + A computer screenshot image used with the computer use tool. + + - `type: "computer_screenshot"` + + Specifies the event type. For a computer screenshot, this property is + always set to `computer_screenshot`. + + - `"computer_screenshot"` + + - `file_id: optional string` + + The identifier of an uploaded file that contains the screenshot. + + - `image_url: optional string` + + The URL of the screenshot image. + + - `status: "completed" or "incomplete" or "failed" or "in_progress"` + + The status of the message input. One of `in_progress`, `completed`, or + `incomplete`. Populated when input items are returned via API. + + - `"completed"` + + - `"incomplete"` + + - `"failed"` + + - `"in_progress"` + + - `type: "computer_call_output"` + + The type of the computer tool call output. Always `computer_call_output`. + + - `"computer_call_output"` + + - `acknowledged_safety_checks: optional array of object { id, code, message }` + + The safety checks reported by the API that have been acknowledged by the + developer. + + - `id: string` The ID of the pending safety check. @@ -12739,11 +14958,11 @@ List all items for a conversation with the given ID. - `"incomplete"` - - `tools: array of object { name, parameters, strict, 3 more } or object { type, vector_store_ids, filters, 2 more } or object { type } or 12 more` + - `tools: array of object { name, parameters, strict, 5 more } or object { type, vector_store_ids, filters, 2 more } or object { type } or 13 more` The loaded tool definitions returned by tool search. - - `Function object { name, parameters, strict, 3 more }` + - `Function object { name, parameters, strict, 5 more }` Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). @@ -12757,7 +14976,7 @@ List all items for a conversation with the given ID. - `strict: boolean` - Whether to enforce strict parameter validation. Default `true`. + Whether strict parameter validation is enforced for this function tool. - `type: "function"` @@ -12765,6 +14984,14 @@ List all items for a conversation with the given ID. - `"function"` + - `allowed_callers: optional array of "direct" or "programmatic"` + + The tool invocation context(s). + + - `"direct"` + + - `"programmatic"` + - `defer_loading: optional boolean` Whether this function is deferred and loaded via tool search. @@ -12773,6 +15000,10 @@ List all items for a conversation with the given ID. 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). @@ -12943,7 +15174,7 @@ List all items for a conversation with the given ID. - `WebSearch object { type, filters, search_context_size, user_location }` Search the Internet for sources related to the prompt. Learn more about the - [web search tool](/docs/guides/tools-web-search). + [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - `type: "web_search" or "web_search_2025_08_26"` @@ -13000,10 +15231,10 @@ List all items for a conversation with the given ID. - `"approximate"` - - `Mcp object { server_label, type, allowed_tools, 8 more }` + - `Mcp object { server_label, type, allowed_callers, 9 more }` Give the model access to additional tools via remote Model Context Protocol - (MCP) servers. [Learn more about MCP](/docs/guides/tools-remote-mcp). + (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). - `server_label: string` @@ -13015,6 +15246,14 @@ List all items for a conversation with the given ID. - `"mcp"` + - `allowed_callers: optional array of "direct" or "programmatic"` + + The tool invocation context(s). + + - `"direct"` + + - `"programmatic"` + - `allowed_tools: optional array of string or object { read_only, tool_names }` List of allowed tool names or a filter object. @@ -13047,7 +15286,7 @@ List all items for a conversation with the given ID. Identifier for service connectors, like those available in ChatGPT. One of `server_url`, `connector_id`, or `tunnel_id` must be provided. Learn more - about service connectors [here](/docs/guides/tools-remote-mcp#connectors). + about service connectors [here](https://platform.openai.com/docs/guides/tools-remote-mcp#connectors). Currently supported `connector_id` values are: @@ -13147,7 +15386,7 @@ List all items for a conversation with the given ID. The Secure MCP Tunnel ID to use instead of a direct server URL. One of `server_url`, `connector_id`, or `tunnel_id` must be provided. - - `CodeInterpreter object { container, type }` + - `CodeInterpreter object { container, type, allowed_callers }` A tool that runs Python code to help generate a response to a prompt. @@ -13233,6 +15472,22 @@ List all items for a conversation with the given ID. - `"code_interpreter"` + - `allowed_callers: optional array of "direct" or "programmatic"` + + The tool invocation context(s). + + - `"direct"` + + - `"programmatic"` + + - `ProgrammaticToolCalling object { type }` + + - `type: "programmatic_tool_calling"` + + The type of the tool. Always `programmatic_tool_calling`. + + - `"programmatic_tool_calling"` + - `ImageGeneration object { type, action, background, 9 more }` A tool that generates images using the GPT image models. @@ -13255,8 +15510,19 @@ List all items for a conversation with the given ID. - `background: optional "transparent" or "opaque" or "auto"` - Background type for the generated image. One of `transparent`, - `opaque`, or `auto`. Default: `auto`. + Allows to set transparency for the background of the generated image(s). + This parameter is only supported for GPT image models that support + transparent backgrounds. Must be one of `transparent`, `opaque`, or + `auto` (default value). When `auto` is used, the model will + automatically determine the best background for the image. + + `gpt-image-2` and `gpt-image-2-2026-04-21` do not support + transparent backgrounds. Requests with `background` set to + `transparent` will return an error for these models; use `opaque` or + `auto` instead. + + If `transparent`, the output format needs to support transparency, + so it should be set to either `png` (default value) or `webp`. - `"transparent"` @@ -13285,13 +15551,13 @@ List all items for a conversation with the given ID. Base64-encoded mask image. - - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` + - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-2" or 3 more` The image generation model to use. Default: `gpt-image-1`. - `string` - - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` + - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-2" or 3 more` The image generation model to use. Default: `gpt-image-1`. @@ -13299,8 +15565,14 @@ List all items for a conversation with the given ID. - `"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`. @@ -13369,7 +15641,7 @@ List all items for a conversation with the given ID. - `"local_shell"` - - `Shell object { type, environment }` + - `Shell object { type, allowed_callers, environment }` A tool that allows the model to execute shell commands. @@ -13379,6 +15651,14 @@ List all items for a conversation with the given ID. - `"shell"` + - `allowed_callers: optional array of "direct" or "programmatic"` + + The tool invocation context(s). + + - `"direct"` + + - `"programmatic"` + - `environment: optional ContainerAuto or LocalEnvironment or ContainerReference` - `ContainerAuto object { type, file_ids, memory_limit, 2 more }` @@ -13505,9 +15785,9 @@ List all items for a conversation with the given ID. - `"container_reference"` - - `Custom object { name, type, defer_loading, 2 more }` + - `Custom object { name, type, allowed_callers, 3 more }` - A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) - `name: string` @@ -13519,6 +15799,14 @@ List all items for a conversation with the given ID. - `"custom"` + - `allowed_callers: optional array of "direct" or "programmatic"` + + The tool invocation context(s). + + - `"direct"` + + - `"programmatic"` + - `defer_loading: optional boolean` Whether this tool should be deferred and discovered via tool search. @@ -13575,11 +15863,11 @@ List all items for a conversation with the given ID. The namespace name used in tool calls (for example, `crm`). - - `tools: array of object { name, type, defer_loading, 3 more } or object { name, type, defer_loading, 2 more }` + - `tools: array of object { name, type, allowed_callers, 5 more } or object { name, type, allowed_callers, 3 more }` The function/custom tools available inside this namespace. - - `Function object { name, type, defer_loading, 3 more }` + - `Function object { name, type, allowed_callers, 5 more }` - `name: string` @@ -13587,19 +15875,33 @@ List all items for a conversation with the given ID. - `"function"` + - `allowed_callers: optional array of "direct" or "programmatic"` + + The tool invocation context(s). + + - `"direct"` + + - `"programmatic"` + - `defer_loading: optional boolean` Whether this function should be deferred and discovered via tool search. - `description: optional string` + - `output_schema: optional map[unknown]` + + A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. + - `parameters: optional unknown` - `strict: optional boolean` - - `Custom object { name, type, defer_loading, 2 more }` + Whether to enforce strict parameter validation. If omitted, Responses attempts to use strict validation when the schema is compatible, and falls back to non-strict validation otherwise. + + - `Custom object { name, type, allowed_callers, 3 more }` - A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) - `name: string` @@ -13611,6 +15913,14 @@ List all items for a conversation with the given ID. - `"custom"` + - `allowed_callers: optional array of "direct" or "programmatic"` + + The tool invocation context(s). + + - `"direct"` + + - `"programmatic"` + - `defer_loading: optional boolean` Whether this tool should be deferred and discovered via tool search. @@ -13709,7 +16019,7 @@ List all items for a conversation with the given ID. The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - - `ApplyPatch object { type }` + - `ApplyPatch object { type, allowed_callers }` Allows the assistant to create, delete, or update files using unified diffs. @@ -13719,6 +16029,14 @@ List all items for a conversation with the given ID. - `"apply_patch"` + - `allowed_callers: optional array of "direct" or "programmatic"` + + The tool invocation context(s). + + - `"direct"` + + - `"programmatic"` + - `type: "tool_search_output"` The type of the item. Always `tool_search_output`. @@ -13755,11 +16073,11 @@ List all items for a conversation with the given ID. - `"tool"` - - `tools: array of object { name, parameters, strict, 3 more } or object { type, vector_store_ids, filters, 2 more } or object { type } or 12 more` + - `tools: array of object { name, parameters, strict, 5 more } or object { type, vector_store_ids, filters, 2 more } or object { type } or 13 more` The additional tool definitions made available at this item. - - `Function object { name, parameters, strict, 3 more }` + - `Function object { name, parameters, strict, 5 more }` Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). @@ -13773,7 +16091,7 @@ List all items for a conversation with the given ID. - `strict: boolean` - Whether to enforce strict parameter validation. Default `true`. + Whether strict parameter validation is enforced for this function tool. - `type: "function"` @@ -13781,6 +16099,14 @@ List all items for a conversation with the given ID. - `"function"` + - `allowed_callers: optional array of "direct" or "programmatic"` + + The tool invocation context(s). + + - `"direct"` + + - `"programmatic"` + - `defer_loading: optional boolean` Whether this function is deferred and loaded via tool search. @@ -13789,6 +16115,10 @@ List all items for a conversation with the given ID. 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). @@ -13892,7 +16222,7 @@ List all items for a conversation with the given ID. - `WebSearch object { type, filters, search_context_size, user_location }` Search the Internet for sources related to the prompt. Learn more about the - [web search tool](/docs/guides/tools-web-search). + [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - `type: "web_search" or "web_search_2025_08_26"` @@ -13949,10 +16279,10 @@ List all items for a conversation with the given ID. - `"approximate"` - - `Mcp object { server_label, type, allowed_tools, 8 more }` + - `Mcp object { server_label, type, allowed_callers, 9 more }` Give the model access to additional tools via remote Model Context Protocol - (MCP) servers. [Learn more about MCP](/docs/guides/tools-remote-mcp). + (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). - `server_label: string` @@ -13964,6 +16294,14 @@ List all items for a conversation with the given ID. - `"mcp"` + - `allowed_callers: optional array of "direct" or "programmatic"` + + The tool invocation context(s). + + - `"direct"` + + - `"programmatic"` + - `allowed_tools: optional array of string or object { read_only, tool_names }` List of allowed tool names or a filter object. @@ -13996,7 +16334,7 @@ List all items for a conversation with the given ID. Identifier for service connectors, like those available in ChatGPT. One of `server_url`, `connector_id`, or `tunnel_id` must be provided. Learn more - about service connectors [here](/docs/guides/tools-remote-mcp#connectors). + about service connectors [here](https://platform.openai.com/docs/guides/tools-remote-mcp#connectors). Currently supported `connector_id` values are: @@ -14096,7 +16434,7 @@ List all items for a conversation with the given ID. The Secure MCP Tunnel ID to use instead of a direct server URL. One of `server_url`, `connector_id`, or `tunnel_id` must be provided. - - `CodeInterpreter object { container, type }` + - `CodeInterpreter object { container, type, allowed_callers }` A tool that runs Python code to help generate a response to a prompt. @@ -14150,6 +16488,22 @@ List all items for a conversation with the given ID. - `"code_interpreter"` + - `allowed_callers: optional array of "direct" or "programmatic"` + + The tool invocation context(s). + + - `"direct"` + + - `"programmatic"` + + - `ProgrammaticToolCalling object { type }` + + - `type: "programmatic_tool_calling"` + + The type of the tool. Always `programmatic_tool_calling`. + + - `"programmatic_tool_calling"` + - `ImageGeneration object { type, action, background, 9 more }` A tool that generates images using the GPT image models. @@ -14172,8 +16526,19 @@ List all items for a conversation with the given ID. - `background: optional "transparent" or "opaque" or "auto"` - Background type for the generated image. One of `transparent`, - `opaque`, or `auto`. Default: `auto`. + Allows to set transparency for the background of the generated image(s). + This parameter is only supported for GPT image models that support + transparent backgrounds. Must be one of `transparent`, `opaque`, or + `auto` (default value). When `auto` is used, the model will + automatically determine the best background for the image. + + `gpt-image-2` and `gpt-image-2-2026-04-21` do not support + transparent backgrounds. Requests with `background` set to + `transparent` will return an error for these models; use `opaque` or + `auto` instead. + + If `transparent`, the output format needs to support transparency, + so it should be set to either `png` (default value) or `webp`. - `"transparent"` @@ -14202,13 +16567,13 @@ List all items for a conversation with the given ID. Base64-encoded mask image. - - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` + - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-2" or 3 more` The image generation model to use. Default: `gpt-image-1`. - `string` - - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` + - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-2" or 3 more` The image generation model to use. Default: `gpt-image-1`. @@ -14216,8 +16581,14 @@ List all items for a conversation with the given ID. - `"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`. @@ -14286,7 +16657,7 @@ List all items for a conversation with the given ID. - `"local_shell"` - - `Shell object { type, environment }` + - `Shell object { type, allowed_callers, environment }` A tool that allows the model to execute shell commands. @@ -14296,6 +16667,14 @@ List all items for a conversation with the given ID. - `"shell"` + - `allowed_callers: optional array of "direct" or "programmatic"` + + The tool invocation context(s). + + - `"direct"` + + - `"programmatic"` + - `environment: optional ContainerAuto or LocalEnvironment or ContainerReference` - `ContainerAuto object { type, file_ids, memory_limit, 2 more }` @@ -14304,9 +16683,9 @@ List all items for a conversation with the given ID. - `ContainerReference object { container_id, type }` - - `Custom object { name, type, defer_loading, 2 more }` + - `Custom object { name, type, allowed_callers, 3 more }` - A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) - `name: string` @@ -14318,6 +16697,14 @@ List all items for a conversation with the given ID. - `"custom"` + - `allowed_callers: optional array of "direct" or "programmatic"` + + The tool invocation context(s). + + - `"direct"` + + - `"programmatic"` + - `defer_loading: optional boolean` Whether this tool should be deferred and discovered via tool search. @@ -14342,11 +16729,11 @@ List all items for a conversation with the given ID. The namespace name used in tool calls (for example, `crm`). - - `tools: array of object { name, type, defer_loading, 3 more } or object { name, type, defer_loading, 2 more }` + - `tools: array of object { name, type, allowed_callers, 5 more } or object { name, type, allowed_callers, 3 more }` The function/custom tools available inside this namespace. - - `Function object { name, type, defer_loading, 3 more }` + - `Function object { name, type, allowed_callers, 5 more }` - `name: string` @@ -14354,19 +16741,33 @@ List all items for a conversation with the given ID. - `"function"` + - `allowed_callers: optional array of "direct" or "programmatic"` + + The tool invocation context(s). + + - `"direct"` + + - `"programmatic"` + - `defer_loading: optional boolean` Whether this function should be deferred and discovered via tool search. - `description: optional string` + - `output_schema: optional map[unknown]` + + A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. + - `parameters: optional unknown` - `strict: optional boolean` - - `Custom object { name, type, defer_loading, 2 more }` + Whether to enforce strict parameter validation. If omitted, Responses attempts to use strict validation when the schema is compatible, and falls back to non-strict validation otherwise. + + - `Custom object { name, type, allowed_callers, 3 more }` - A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) - `name: string` @@ -14378,6 +16779,14 @@ List all items for a conversation with the given ID. - `"custom"` + - `allowed_callers: optional array of "direct" or "programmatic"` + + The tool invocation context(s). + + - `"direct"` + + - `"programmatic"` + - `defer_loading: optional boolean` Whether this tool should be deferred and discovered via tool search. @@ -14476,7 +16885,7 @@ List all items for a conversation with the given ID. The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - - `ApplyPatch object { type }` + - `ApplyPatch object { type, allowed_callers }` Allows the assistant to create, delete, or update files using unified diffs. @@ -14486,6 +16895,14 @@ List all items for a conversation with the given ID. - `"apply_patch"` + - `allowed_callers: optional array of "direct" or "programmatic"` + + The tool invocation context(s). + + - `"direct"` + + - `"programmatic"` + - `type: "additional_tools"` The type of the item. Always `additional_tools`. @@ -14497,13 +16914,13 @@ List all items for a conversation with the given ID. A description of the chain of thought used by a reasoning model while generating a response. Be sure to include these items in your `input` to the Responses API for subsequent turns of a conversation if you are manually - [managing context](/docs/guides/conversation-state). + [managing context](https://platform.openai.com/docs/guides/conversation-state). - `id: string` The unique identifier of the reasoning content. - - `summary: array of SummaryTextContent` + - `summary: array of object { text, type }` Reasoning summary content. @@ -14515,6 +16932,8 @@ List all items for a conversation with the given ID. The type of the object. Always `summary_text`. + - `"summary_text"` + - `type: "reasoning"` The type of the object. Always `reasoning`. @@ -14551,19 +16970,71 @@ List all items for a conversation with the given ID. - `"incomplete"` - - `Compaction object { id, encrypted_content, type, created_by }` - - A compaction item generated by the [`v1/responses/compact` API](/docs/api-reference/responses/compact). + - `Program object { id, call_id, code, 2 more }` - `id: string` - The unique ID of the compaction item. + The unique ID of the program item. - - `encrypted_content: string` + - `call_id: string` - The encrypted content that was produced by compaction. + The stable call ID of the program item. - - `type: "compaction"` + - `code: string` + + The JavaScript source executed by programmatic tool calling. + + - `fingerprint: string` + + Opaque program replay fingerprint that must be round-tripped. + + - `type: "program"` + + The type of the item. Always `program`. + + - `"program"` + + - `ProgramOutput object { id, call_id, result, 2 more }` + + - `id: string` + + The unique ID of the program output item. + + - `call_id: string` + + The call ID of the program item. + + - `result: string` + + The result produced by the program item. + + - `status: "completed" or "incomplete"` + + The terminal status of the program output item. + + - `"completed"` + + - `"incomplete"` + + - `type: "program_output"` + + The type of the item. Always `program_output`. + + - `"program_output"` + + - `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). + + - `id: string` + + The unique ID of the compaction item. + + - `encrypted_content: string` + + The encrypted content that was produced by compaction. + + - `type: "compaction"` The type of the item. Always `compaction`. @@ -14728,7 +17199,7 @@ List all items for a conversation with the given ID. - `"incomplete"` - - `ShellCall object { id, action, call_id, 4 more }` + - `ShellCall object { id, action, call_id, 5 more }` A tool call that executes one or more shell commands in a managed environment. @@ -14796,11 +17267,31 @@ List all items for a conversation with the given ID. - `"shell_call"` + - `caller: optional object { type } or object { caller_id, type }` + + The execution context that produced this tool call. + + - `Direct object { type }` + + - `type: "direct"` + + - `"direct"` + + - `Program object { caller_id, type }` + + - `caller_id: string` + + The call ID of the program item that produced this tool call. + + - `type: "program"` + + - `"program"` + - `created_by: optional string` The ID of the entity that created this tool call. - - `ShellCallOutput object { id, call_id, max_output_length, 4 more }` + - `ShellCallOutput object { id, call_id, max_output_length, 5 more }` The output of a shell tool call that was emitted. @@ -14876,11 +17367,31 @@ List all items for a conversation with the given ID. - `"shell_call_output"` + - `caller: optional object { type } or object { caller_id, type }` + + The execution context that produced this tool call. + + - `Direct object { type }` + + - `type: "direct"` + + - `"direct"` + + - `Program object { caller_id, type }` + + - `caller_id: string` + + The call ID of the program item that produced this tool call. + + - `type: "program"` + + - `"program"` + - `created_by: optional string` The identifier of the actor that created the item. - - `ApplyPatchCall object { id, call_id, operation, 3 more }` + - `ApplyPatchCall object { id, call_id, operation, 4 more }` A tool call that applies file diffs by creating, deleting, or updating files. @@ -14960,11 +17471,31 @@ List all items for a conversation with the given ID. - `"apply_patch_call"` + - `caller: optional object { type } or object { caller_id, type }` + + The execution context that produced this tool call. + + - `Direct object { type }` + + - `type: "direct"` + + - `"direct"` + + - `Program object { caller_id, type }` + + - `caller_id: string` + + The call ID of the program item that produced this tool call. + + - `type: "program"` + + - `"program"` + - `created_by: optional string` The ID of the entity that created this tool call. - - `ApplyPatchCallOutput object { id, call_id, status, 3 more }` + - `ApplyPatchCallOutput object { id, call_id, status, 4 more }` The output emitted by an apply patch tool call. @@ -14990,6 +17521,26 @@ List all items for a conversation with the given ID. - `"apply_patch_call_output"` + - `caller: optional object { type } or object { caller_id, type }` + + The execution context that produced this tool call. + + - `Direct object { type }` + + - `type: "direct"` + + - `"direct"` + + - `Program object { caller_id, type }` + + - `caller_id: string` + + The call ID of the program item that produced this tool call. + + - `type: "program"` + + - `"program"` + - `created_by: optional string` The ID of the entity that created this tool call output. @@ -15145,7 +17696,7 @@ List all items for a conversation with the given ID. - `"failed"` - - `CustomToolCall object { call_id, input, name, 3 more }` + - `CustomToolCall object { call_id, input, name, 4 more }` A call to a custom tool created by the model. @@ -15171,11 +17722,31 @@ List all items for a conversation with the given ID. The unique ID of the custom tool call in the OpenAI platform. + - `caller: optional object { type } or object { caller_id, type }` + + The execution context that produced this tool call. + + - `Direct object { type }` + + - `type: "direct"` + + - `"direct"` + + - `Program object { caller_id, type }` + + - `caller_id: string` + + The call ID of the program item that produced this tool call. + + - `type: "program"` + + - `"program"` + - `namespace: optional string` The namespace of the custom tool being called. - - `CustomToolCallOutput object { call_id, output, type, id }` + - `CustomToolCallOutput object { call_id, output, type, 2 more }` The output of a custom tool call from your code, being sent back to the model. @@ -15196,15 +17767,15 @@ List all items for a conversation with the given ID. Text, image, or file output of the custom tool call. - - `ResponseInputText object { text, type }` + - `ResponseInputText object { text, type, prompt_cache_breakpoint }` A text input to the model. - - `ResponseInputImage object { detail, type, file_id, image_url }` + - `ResponseInputImage object { detail, type, file_id, 2 more }` - An image input to the model. Learn about [image inputs](/docs/guides/vision). + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - `ResponseInputFile object { type, detail, file_data, 3 more }` + - `ResponseInputFile object { type, detail, file_data, 4 more }` A file input to the model. @@ -15218,6 +17789,30 @@ List all items for a conversation with the given ID. 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. + + - `Direct object { type }` + + - `type: "direct"` + + The caller type. Always `direct`. + + - `"direct"` + + - `Program object { caller_id, type }` + + - `caller_id: string` + + The call ID of the program item that produced this tool call. + + - `type: "program"` + + The caller type. Always `program`. + + - `"program"` + - `first_id: string` The ID of the first item in the list. @@ -15253,7 +17848,10 @@ curl https://api.openai.com/v1/conversations/$CONVERSATION_ID/items \ "content": [ { "text": "text", - "type": "input_text" + "type": "input_text", + "prompt_cache_breakpoint": { + "mode": "explicit" + } } ], "role": "unknown", @@ -15302,7 +17900,7 @@ curl "https://api.openai.com/v1/conversations/conv_123/items?limit=10" \ **get** `/conversations/{conversation_id}/items/{item_id}` -Get a single item from a conversation with the given IDs. +Retrieve an item ### Path Parameters @@ -15315,7 +17913,7 @@ Get a single item from a conversation with the given IDs. - `include: optional array of ResponseIncludable` Additional fields to include in the response. See the `include` - parameter for [listing Conversation items above](/docs/api-reference/conversations/list-items#conversations_list_items-include) for more information. + parameter for [listing Conversation items above](https://platform.openai.com/docs/api-reference/conversations/list-items#conversations_list_items-include) for more information. - `"file_search_call.results"` @@ -15335,9 +17933,9 @@ Get a single item from a conversation with the given IDs. ### Returns -- `ConversationItem = Message or object { id, arguments, call_id, 5 more } or object { id, call_id, output, 3 more } or 23 more` +- `ConversationItem = Message or object { id, arguments, call_id, 6 more } or object { id, call_id, output, 4 more } or 25 more` - A single item within a conversation. The set of possible types are the same as the `output` type of a [Response object](/docs/api-reference/responses/object#responses/object-output). + A single item within a conversation. The set of possible types are the same as the `output` type of a [Response object](https://platform.openai.com/docs/api-reference/responses/object#responses/object-output). - `Message object { id, content, role, 3 more }` @@ -15351,7 +17949,7 @@ Get a single item from a conversation with the given IDs. The content of the message - - `ResponseInputText object { text, type }` + - `ResponseInputText object { text, type, prompt_cache_breakpoint }` A text input to the model. @@ -15365,7 +17963,17 @@ Get a single item from a conversation with the given IDs. - `"input_text"` - - `ResponseOutputText object { annotations, logprobs, text, type }` + - `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 }` A text output from the model. @@ -15469,15 +18077,17 @@ Get a single item from a conversation with the given IDs. - `"file_path"` - - `logprobs: array of object { token, bytes, logprob, top_logprobs }` + - `text: string` - - `token: string` + The text output from the model. - - `bytes: array of number` + - `type: "output_text"` - - `logprob: number` + The type of the output text. Always `output_text`. - - `top_logprobs: array of object { token, bytes, logprob }` + - `"output_text"` + + - `logprobs: optional array of object { token, bytes, logprob, top_logprobs }` - `token: string` @@ -15485,15 +18095,13 @@ Get a single item from a conversation with the given IDs. - `logprob: number` - - `text: string` - - The text output from the model. + - `top_logprobs: array of object { token, bytes, logprob }` - - `type: "output_text"` + - `token: string` - The type of the output text. Always `output_text`. + - `bytes: array of number` - - `"output_text"` + - `logprob: number` - `TextContent object { text, type }` @@ -15547,9 +18155,9 @@ Get a single item from a conversation with the given IDs. - `"refusal"` - - `ResponseInputImage object { detail, type, file_id, image_url }` + - `ResponseInputImage object { detail, type, file_id, 2 more }` - An image input to the model. Learn about [image inputs](/docs/guides/vision). + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - `detail: "low" or "high" or "auto" or "original"` @@ -15577,7 +18185,17 @@ Get a single item from a conversation with the given IDs. The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - - `ComputerScreenshotContent object { detail, file_id, image_url, type }` + - `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"` + + - `ComputerScreenshotContent object { detail, file_id, image_url, 2 more }` A screenshot of a computer. @@ -15607,7 +18225,17 @@ Get a single item from a conversation with the given IDs. - `"computer_screenshot"` - - `ResponseInputFile object { type, detail, file_data, 3 more }` + - `prompt_cache_breakpoint: optional object { mode }` + + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + + - `mode: "explicit"` + + The breakpoint mode. Always `explicit`. + + - `"explicit"` + + - `ResponseInputFile object { type, detail, file_data, 4 more }` A file input to the model. @@ -15617,9 +18245,11 @@ Get a single item from a conversation with the given IDs. - `"input_file"` - - `detail: optional "low" or "high"` + - `detail: optional "auto" or "low" or "high"` - The detail level of the file to be sent to the model. Use `low` for the default rendering behavior, or `high` to render the file at higher quality. Defaults to `low`. + The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. + + - `"auto"` - `"low"` @@ -15641,6 +18271,16 @@ Get a single item from a conversation with the given IDs. The name of the file to be sent to the model. + - `prompt_cache_breakpoint: optional object { mode }` + + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + + - `mode: "explicit"` + + The breakpoint mode. Always `explicit`. + + - `"explicit"` + - `role: "unknown" or "user" or "assistant" or 5 more` The role of the message. One of `unknown`, `user`, `assistant`, `system`, `critic`, `discriminator`, `developer`, or `tool`. @@ -15685,7 +18325,7 @@ Get a single item from a conversation with the given IDs. - `"final_answer"` - - `FunctionCall object { id, arguments, call_id, 5 more }` + - `FunctionCall object { id, arguments, call_id, 6 more }` - `id: string` @@ -15720,6 +18360,26 @@ Get a single item from a conversation with the given IDs. - `"function_call"` + - `caller: optional object { type } or object { caller_id, type }` + + The execution context that produced this tool call. + + - `Direct object { type }` + + - `type: "direct"` + + - `"direct"` + + - `Program object { caller_id, type }` + + - `caller_id: string` + + The call ID of the program item that produced this tool call. + + - `type: "program"` + + - `"program"` + - `created_by: optional string` The identifier of the actor that created the item. @@ -15728,7 +18388,7 @@ Get a single item from a conversation with the given IDs. The namespace of the function to run. - - `FunctionCallOutput object { id, call_id, output, 3 more }` + - `FunctionCallOutput object { id, call_id, output, 4 more }` - `id: string` @@ -15751,15 +18411,15 @@ Get a single item from a conversation with the given IDs. Text, image, or file output of the function call. - - `ResponseInputText object { text, type }` + - `ResponseInputText object { text, type, prompt_cache_breakpoint }` A text input to the model. - - `ResponseInputImage object { detail, type, file_id, image_url }` + - `ResponseInputImage object { detail, type, file_id, 2 more }` - An image input to the model. Learn about [image inputs](/docs/guides/vision). + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - `ResponseInputFile object { type, detail, file_data, 3 more }` + - `ResponseInputFile object { type, detail, file_data, 4 more }` A file input to the model. @@ -15780,6 +18440,30 @@ Get a single item from a conversation with the given IDs. - `"function_call_output"` + - `caller: optional object { type } or object { caller_id, type }` + + The execution context that produced this tool call. + + - `Direct object { type }` + + - `type: "direct"` + + The caller type. Always `direct`. + + - `"direct"` + + - `Program object { caller_id, type }` + + - `caller_id: string` + + The call ID of the program item that produced this tool call. + + - `type: "program"` + + The caller type. Always `program`. + + - `"program"` + - `created_by: optional string` The identifier of the actor that created the item. @@ -15787,7 +18471,7 @@ Get a single item from a conversation with the given IDs. - `FileSearchCall object { id, queries, status, 2 more }` The results of a file search tool call. See the - [file search guide](/docs/guides/tools-file-search) for more information. + [file search guide](https://platform.openai.com/docs/guides/tools-file-search) for more information. - `id: string` @@ -15855,7 +18539,7 @@ Get a single item from a conversation with the given IDs. - `WebSearchCall object { id, action, status, type }` The results of a web search tool call. See the - [web search guide](/docs/guides/tools-web-search) for more information. + [web search guide](https://platform.openai.com/docs/guides/tools-web-search) for more information. - `id: string` @@ -15981,7 +18665,7 @@ Get a single item from a conversation with the given IDs. - `ComputerCall object { id, call_id, pending_safety_checks, 4 more }` A tool call to a computer use tool. See the - [computer use guide](/docs/guides/tools-computer-use) for more information. + [computer use guide](https://platform.openai.com/docs/guides/tools-computer-use) for more information. - `id: string` @@ -16024,7 +18708,7 @@ Get a single item from a conversation with the given IDs. - `"computer_call"` - - `action: optional ComputerAction` + - `action: optional object { button, type, x, 2 more } or object { keys, type, x, y } or object { path, type, keys } or 6 more` A click action. @@ -16228,92 +18912,247 @@ Get a single item from a conversation with the given IDs. A click action. - - `DoubleClick object { keys, type, x, y }` + - `button: "left" or "right" or "wheel" or 2 more` - A double click action. + Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. - - `Drag object { path, type, keys }` + - `"left"` - A drag action. + - `"right"` - - `Keypress object { keys, type }` + - `"wheel"` - A collection of keypresses the model would like to perform. + - `"back"` - - `Move object { type, x, y, keys }` + - `"forward"` - A mouse move action. + - `type: "click"` - - `Screenshot object { type }` + Specifies the event type. For a click action, this property is always `click`. - A screenshot action. + - `"click"` - - `Scroll object { scroll_x, scroll_y, type, 3 more }` + - `x: number` - A scroll action. + The x-coordinate where the click occurred. - - `Type object { text, type }` + - `y: number` - An action to type in text. + The y-coordinate where the click occurred. - - `Wait object { type }` + - `keys: optional array of string` - A wait action. + The keys being held while clicking. - - `ComputerCallOutput object { id, call_id, output, 4 more }` + - `DoubleClick object { keys, type, x, y }` - - `id: string` + A double click action. - The unique ID of the computer call tool output. + - `keys: array of string` - - `call_id: string` + The keys being held while double-clicking. - The ID of the computer tool call that produced the output. + - `type: "double_click"` - - `output: ResponseComputerToolCallOutputScreenshot` + Specifies the event type. For a double click action, this property is always set to `double_click`. - A computer screenshot image used with the computer use tool. + - `"double_click"` - - `type: "computer_screenshot"` + - `x: number` - Specifies the event type. For a computer screenshot, this property is - always set to `computer_screenshot`. + The x-coordinate where the double click occurred. - - `"computer_screenshot"` + - `y: number` - - `file_id: optional string` + The y-coordinate where the double click occurred. - The identifier of an uploaded file that contains the screenshot. + - `Drag object { path, type, keys }` - - `image_url: optional string` + A drag action. - The URL of the screenshot image. + - `path: array of object { x, y }` - - `status: "completed" or "incomplete" or "failed" or "in_progress"` + An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg - The status of the message input. One of `in_progress`, `completed`, or - `incomplete`. Populated when input items are returned via API. + ``` + [ + { x: 100, y: 200 }, + { x: 200, y: 300 } + ] + ``` - - `"completed"` + - `x: number` - - `"incomplete"` + The x-coordinate. - - `"failed"` + - `y: number` - - `"in_progress"` + The y-coordinate. - - `type: "computer_call_output"` + - `type: "drag"` - The type of the computer tool call output. Always `computer_call_output`. + Specifies the event type. For a drag action, this property is always set to `drag`. - - `"computer_call_output"` + - `"drag"` - - `acknowledged_safety_checks: optional array of object { id, code, message }` + - `keys: optional array of string` - The safety checks reported by the API that have been acknowledged by the - developer. + The keys being held while dragging the mouse. - - `id: string` + - `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 { id, call_id, output, 4 more }` + + - `id: string` + + The unique ID of the computer call tool output. + + - `call_id: string` + + The ID of the computer tool call that produced the output. + + - `output: ResponseComputerToolCallOutputScreenshot` + + A computer screenshot image used with the computer use tool. + + - `type: "computer_screenshot"` + + Specifies the event type. For a computer screenshot, this property is + always set to `computer_screenshot`. + + - `"computer_screenshot"` + + - `file_id: optional string` + + The identifier of an uploaded file that contains the screenshot. + + - `image_url: optional string` + + The URL of the screenshot image. + + - `status: "completed" or "incomplete" or "failed" or "in_progress"` + + The status of the message input. One of `in_progress`, `completed`, or + `incomplete`. Populated when input items are returned via API. + + - `"completed"` + + - `"incomplete"` + + - `"failed"` + + - `"in_progress"` + + - `type: "computer_call_output"` + + The type of the computer tool call output. Always `computer_call_output`. + + - `"computer_call_output"` + + - `acknowledged_safety_checks: optional array of object { id, code, message }` + + The safety checks reported by the API that have been acknowledged by the + developer. + + - `id: string` The ID of the pending safety check. @@ -16399,11 +19238,11 @@ Get a single item from a conversation with the given IDs. - `"incomplete"` - - `tools: array of object { name, parameters, strict, 3 more } or object { type, vector_store_ids, filters, 2 more } or object { type } or 12 more` + - `tools: array of object { name, parameters, strict, 5 more } or object { type, vector_store_ids, filters, 2 more } or object { type } or 13 more` The loaded tool definitions returned by tool search. - - `Function object { name, parameters, strict, 3 more }` + - `Function object { name, parameters, strict, 5 more }` Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). @@ -16417,7 +19256,7 @@ Get a single item from a conversation with the given IDs. - `strict: boolean` - Whether to enforce strict parameter validation. Default `true`. + Whether strict parameter validation is enforced for this function tool. - `type: "function"` @@ -16425,6 +19264,14 @@ Get a single item from a conversation with the given IDs. - `"function"` + - `allowed_callers: optional array of "direct" or "programmatic"` + + The tool invocation context(s). + + - `"direct"` + + - `"programmatic"` + - `defer_loading: optional boolean` Whether this function is deferred and loaded via tool search. @@ -16433,6 +19280,10 @@ Get a single item from a conversation with the given IDs. 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). @@ -16603,7 +19454,7 @@ Get a single item from a conversation with the given IDs. - `WebSearch object { type, filters, search_context_size, user_location }` Search the Internet for sources related to the prompt. Learn more about the - [web search tool](/docs/guides/tools-web-search). + [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - `type: "web_search" or "web_search_2025_08_26"` @@ -16660,10 +19511,10 @@ Get a single item from a conversation with the given IDs. - `"approximate"` - - `Mcp object { server_label, type, allowed_tools, 8 more }` + - `Mcp object { server_label, type, allowed_callers, 9 more }` Give the model access to additional tools via remote Model Context Protocol - (MCP) servers. [Learn more about MCP](/docs/guides/tools-remote-mcp). + (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). - `server_label: string` @@ -16675,6 +19526,14 @@ Get a single item from a conversation with the given IDs. - `"mcp"` + - `allowed_callers: optional array of "direct" or "programmatic"` + + The tool invocation context(s). + + - `"direct"` + + - `"programmatic"` + - `allowed_tools: optional array of string or object { read_only, tool_names }` List of allowed tool names or a filter object. @@ -16707,7 +19566,7 @@ Get a single item from a conversation with the given IDs. Identifier for service connectors, like those available in ChatGPT. One of `server_url`, `connector_id`, or `tunnel_id` must be provided. Learn more - about service connectors [here](/docs/guides/tools-remote-mcp#connectors). + about service connectors [here](https://platform.openai.com/docs/guides/tools-remote-mcp#connectors). Currently supported `connector_id` values are: @@ -16807,7 +19666,7 @@ Get a single item from a conversation with the given IDs. The Secure MCP Tunnel ID to use instead of a direct server URL. One of `server_url`, `connector_id`, or `tunnel_id` must be provided. - - `CodeInterpreter object { container, type }` + - `CodeInterpreter object { container, type, allowed_callers }` A tool that runs Python code to help generate a response to a prompt. @@ -16893,6 +19752,22 @@ Get a single item from a conversation with the given IDs. - `"code_interpreter"` + - `allowed_callers: optional array of "direct" or "programmatic"` + + The tool invocation context(s). + + - `"direct"` + + - `"programmatic"` + + - `ProgrammaticToolCalling object { type }` + + - `type: "programmatic_tool_calling"` + + The type of the tool. Always `programmatic_tool_calling`. + + - `"programmatic_tool_calling"` + - `ImageGeneration object { type, action, background, 9 more }` A tool that generates images using the GPT image models. @@ -16915,8 +19790,19 @@ Get a single item from a conversation with the given IDs. - `background: optional "transparent" or "opaque" or "auto"` - Background type for the generated image. One of `transparent`, - `opaque`, or `auto`. Default: `auto`. + Allows to set transparency for the background of the generated image(s). + This parameter is only supported for GPT image models that support + transparent backgrounds. Must be one of `transparent`, `opaque`, or + `auto` (default value). When `auto` is used, the model will + automatically determine the best background for the image. + + `gpt-image-2` and `gpt-image-2-2026-04-21` do not support + transparent backgrounds. Requests with `background` set to + `transparent` will return an error for these models; use `opaque` or + `auto` instead. + + If `transparent`, the output format needs to support transparency, + so it should be set to either `png` (default value) or `webp`. - `"transparent"` @@ -16945,13 +19831,13 @@ Get a single item from a conversation with the given IDs. Base64-encoded mask image. - - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` + - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-2" or 3 more` The image generation model to use. Default: `gpt-image-1`. - `string` - - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` + - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-2" or 3 more` The image generation model to use. Default: `gpt-image-1`. @@ -16959,8 +19845,14 @@ Get a single item from a conversation with the given IDs. - `"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`. @@ -17029,7 +19921,7 @@ Get a single item from a conversation with the given IDs. - `"local_shell"` - - `Shell object { type, environment }` + - `Shell object { type, allowed_callers, environment }` A tool that allows the model to execute shell commands. @@ -17039,6 +19931,14 @@ Get a single item from a conversation with the given IDs. - `"shell"` + - `allowed_callers: optional array of "direct" or "programmatic"` + + The tool invocation context(s). + + - `"direct"` + + - `"programmatic"` + - `environment: optional ContainerAuto or LocalEnvironment or ContainerReference` - `ContainerAuto object { type, file_ids, memory_limit, 2 more }` @@ -17165,9 +20065,9 @@ Get a single item from a conversation with the given IDs. - `"container_reference"` - - `Custom object { name, type, defer_loading, 2 more }` + - `Custom object { name, type, allowed_callers, 3 more }` - A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) - `name: string` @@ -17179,6 +20079,14 @@ Get a single item from a conversation with the given IDs. - `"custom"` + - `allowed_callers: optional array of "direct" or "programmatic"` + + The tool invocation context(s). + + - `"direct"` + + - `"programmatic"` + - `defer_loading: optional boolean` Whether this tool should be deferred and discovered via tool search. @@ -17235,11 +20143,11 @@ Get a single item from a conversation with the given IDs. The namespace name used in tool calls (for example, `crm`). - - `tools: array of object { name, type, defer_loading, 3 more } or object { name, type, defer_loading, 2 more }` + - `tools: array of object { name, type, allowed_callers, 5 more } or object { name, type, allowed_callers, 3 more }` The function/custom tools available inside this namespace. - - `Function object { name, type, defer_loading, 3 more }` + - `Function object { name, type, allowed_callers, 5 more }` - `name: string` @@ -17247,19 +20155,33 @@ Get a single item from a conversation with the given IDs. - `"function"` + - `allowed_callers: optional array of "direct" or "programmatic"` + + The tool invocation context(s). + + - `"direct"` + + - `"programmatic"` + - `defer_loading: optional boolean` Whether this function should be deferred and discovered via tool search. - `description: optional string` + - `output_schema: optional map[unknown]` + + A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. + - `parameters: optional unknown` - `strict: optional boolean` - - `Custom object { name, type, defer_loading, 2 more }` + Whether to enforce strict parameter validation. If omitted, Responses attempts to use strict validation when the schema is compatible, and falls back to non-strict validation otherwise. + + - `Custom object { name, type, allowed_callers, 3 more }` - A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) - `name: string` @@ -17271,6 +20193,14 @@ Get a single item from a conversation with the given IDs. - `"custom"` + - `allowed_callers: optional array of "direct" or "programmatic"` + + The tool invocation context(s). + + - `"direct"` + + - `"programmatic"` + - `defer_loading: optional boolean` Whether this tool should be deferred and discovered via tool search. @@ -17369,7 +20299,7 @@ Get a single item from a conversation with the given IDs. The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - - `ApplyPatch object { type }` + - `ApplyPatch object { type, allowed_callers }` Allows the assistant to create, delete, or update files using unified diffs. @@ -17379,6 +20309,14 @@ Get a single item from a conversation with the given IDs. - `"apply_patch"` + - `allowed_callers: optional array of "direct" or "programmatic"` + + The tool invocation context(s). + + - `"direct"` + + - `"programmatic"` + - `type: "tool_search_output"` The type of the item. Always `tool_search_output`. @@ -17415,11 +20353,11 @@ Get a single item from a conversation with the given IDs. - `"tool"` - - `tools: array of object { name, parameters, strict, 3 more } or object { type, vector_store_ids, filters, 2 more } or object { type } or 12 more` + - `tools: array of object { name, parameters, strict, 5 more } or object { type, vector_store_ids, filters, 2 more } or object { type } or 13 more` The additional tool definitions made available at this item. - - `Function object { name, parameters, strict, 3 more }` + - `Function object { name, parameters, strict, 5 more }` Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). @@ -17433,7 +20371,7 @@ Get a single item from a conversation with the given IDs. - `strict: boolean` - Whether to enforce strict parameter validation. Default `true`. + Whether strict parameter validation is enforced for this function tool. - `type: "function"` @@ -17441,6 +20379,14 @@ Get a single item from a conversation with the given IDs. - `"function"` + - `allowed_callers: optional array of "direct" or "programmatic"` + + The tool invocation context(s). + + - `"direct"` + + - `"programmatic"` + - `defer_loading: optional boolean` Whether this function is deferred and loaded via tool search. @@ -17449,6 +20395,10 @@ Get a single item from a conversation with the given IDs. 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). @@ -17552,7 +20502,7 @@ Get a single item from a conversation with the given IDs. - `WebSearch object { type, filters, search_context_size, user_location }` Search the Internet for sources related to the prompt. Learn more about the - [web search tool](/docs/guides/tools-web-search). + [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - `type: "web_search" or "web_search_2025_08_26"` @@ -17609,10 +20559,10 @@ Get a single item from a conversation with the given IDs. - `"approximate"` - - `Mcp object { server_label, type, allowed_tools, 8 more }` + - `Mcp object { server_label, type, allowed_callers, 9 more }` Give the model access to additional tools via remote Model Context Protocol - (MCP) servers. [Learn more about MCP](/docs/guides/tools-remote-mcp). + (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). - `server_label: string` @@ -17624,6 +20574,14 @@ Get a single item from a conversation with the given IDs. - `"mcp"` + - `allowed_callers: optional array of "direct" or "programmatic"` + + The tool invocation context(s). + + - `"direct"` + + - `"programmatic"` + - `allowed_tools: optional array of string or object { read_only, tool_names }` List of allowed tool names or a filter object. @@ -17656,7 +20614,7 @@ Get a single item from a conversation with the given IDs. Identifier for service connectors, like those available in ChatGPT. One of `server_url`, `connector_id`, or `tunnel_id` must be provided. Learn more - about service connectors [here](/docs/guides/tools-remote-mcp#connectors). + about service connectors [here](https://platform.openai.com/docs/guides/tools-remote-mcp#connectors). Currently supported `connector_id` values are: @@ -17756,7 +20714,7 @@ Get a single item from a conversation with the given IDs. The Secure MCP Tunnel ID to use instead of a direct server URL. One of `server_url`, `connector_id`, or `tunnel_id` must be provided. - - `CodeInterpreter object { container, type }` + - `CodeInterpreter object { container, type, allowed_callers }` A tool that runs Python code to help generate a response to a prompt. @@ -17810,6 +20768,22 @@ Get a single item from a conversation with the given IDs. - `"code_interpreter"` + - `allowed_callers: optional array of "direct" or "programmatic"` + + The tool invocation context(s). + + - `"direct"` + + - `"programmatic"` + + - `ProgrammaticToolCalling object { type }` + + - `type: "programmatic_tool_calling"` + + The type of the tool. Always `programmatic_tool_calling`. + + - `"programmatic_tool_calling"` + - `ImageGeneration object { type, action, background, 9 more }` A tool that generates images using the GPT image models. @@ -17832,8 +20806,19 @@ Get a single item from a conversation with the given IDs. - `background: optional "transparent" or "opaque" or "auto"` - Background type for the generated image. One of `transparent`, - `opaque`, or `auto`. Default: `auto`. + Allows to set transparency for the background of the generated image(s). + This parameter is only supported for GPT image models that support + transparent backgrounds. Must be one of `transparent`, `opaque`, or + `auto` (default value). When `auto` is used, the model will + automatically determine the best background for the image. + + `gpt-image-2` and `gpt-image-2-2026-04-21` do not support + transparent backgrounds. Requests with `background` set to + `transparent` will return an error for these models; use `opaque` or + `auto` instead. + + If `transparent`, the output format needs to support transparency, + so it should be set to either `png` (default value) or `webp`. - `"transparent"` @@ -17862,13 +20847,13 @@ Get a single item from a conversation with the given IDs. Base64-encoded mask image. - - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` + - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-2" or 3 more` The image generation model to use. Default: `gpt-image-1`. - `string` - - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` + - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-2" or 3 more` The image generation model to use. Default: `gpt-image-1`. @@ -17876,8 +20861,14 @@ Get a single item from a conversation with the given IDs. - `"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`. @@ -17946,7 +20937,7 @@ Get a single item from a conversation with the given IDs. - `"local_shell"` - - `Shell object { type, environment }` + - `Shell object { type, allowed_callers, environment }` A tool that allows the model to execute shell commands. @@ -17956,6 +20947,14 @@ Get a single item from a conversation with the given IDs. - `"shell"` + - `allowed_callers: optional array of "direct" or "programmatic"` + + The tool invocation context(s). + + - `"direct"` + + - `"programmatic"` + - `environment: optional ContainerAuto or LocalEnvironment or ContainerReference` - `ContainerAuto object { type, file_ids, memory_limit, 2 more }` @@ -17964,9 +20963,9 @@ Get a single item from a conversation with the given IDs. - `ContainerReference object { container_id, type }` - - `Custom object { name, type, defer_loading, 2 more }` + - `Custom object { name, type, allowed_callers, 3 more }` - A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) - `name: string` @@ -17978,6 +20977,14 @@ Get a single item from a conversation with the given IDs. - `"custom"` + - `allowed_callers: optional array of "direct" or "programmatic"` + + The tool invocation context(s). + + - `"direct"` + + - `"programmatic"` + - `defer_loading: optional boolean` Whether this tool should be deferred and discovered via tool search. @@ -18002,11 +21009,11 @@ Get a single item from a conversation with the given IDs. The namespace name used in tool calls (for example, `crm`). - - `tools: array of object { name, type, defer_loading, 3 more } or object { name, type, defer_loading, 2 more }` + - `tools: array of object { name, type, allowed_callers, 5 more } or object { name, type, allowed_callers, 3 more }` The function/custom tools available inside this namespace. - - `Function object { name, type, defer_loading, 3 more }` + - `Function object { name, type, allowed_callers, 5 more }` - `name: string` @@ -18014,19 +21021,33 @@ Get a single item from a conversation with the given IDs. - `"function"` + - `allowed_callers: optional array of "direct" or "programmatic"` + + The tool invocation context(s). + + - `"direct"` + + - `"programmatic"` + - `defer_loading: optional boolean` Whether this function should be deferred and discovered via tool search. - `description: optional string` + - `output_schema: optional map[unknown]` + + A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. + - `parameters: optional unknown` - `strict: optional boolean` - - `Custom object { name, type, defer_loading, 2 more }` + Whether to enforce strict parameter validation. If omitted, Responses attempts to use strict validation when the schema is compatible, and falls back to non-strict validation otherwise. + + - `Custom object { name, type, allowed_callers, 3 more }` - A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) - `name: string` @@ -18038,6 +21059,14 @@ Get a single item from a conversation with the given IDs. - `"custom"` + - `allowed_callers: optional array of "direct" or "programmatic"` + + The tool invocation context(s). + + - `"direct"` + + - `"programmatic"` + - `defer_loading: optional boolean` Whether this tool should be deferred and discovered via tool search. @@ -18136,7 +21165,7 @@ Get a single item from a conversation with the given IDs. The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - - `ApplyPatch object { type }` + - `ApplyPatch object { type, allowed_callers }` Allows the assistant to create, delete, or update files using unified diffs. @@ -18146,6 +21175,14 @@ Get a single item from a conversation with the given IDs. - `"apply_patch"` + - `allowed_callers: optional array of "direct" or "programmatic"` + + The tool invocation context(s). + + - `"direct"` + + - `"programmatic"` + - `type: "additional_tools"` The type of the item. Always `additional_tools`. @@ -18157,13 +21194,13 @@ Get a single item from a conversation with the given IDs. A description of the chain of thought used by a reasoning model while generating a response. Be sure to include these items in your `input` to the Responses API for subsequent turns of a conversation if you are manually - [managing context](/docs/guides/conversation-state). + [managing context](https://platform.openai.com/docs/guides/conversation-state). - `id: string` The unique identifier of the reasoning content. - - `summary: array of SummaryTextContent` + - `summary: array of object { text, type }` Reasoning summary content. @@ -18175,6 +21212,8 @@ Get a single item from a conversation with the given IDs. The type of the object. Always `summary_text`. + - `"summary_text"` + - `type: "reasoning"` The type of the object. Always `reasoning`. @@ -18211,19 +21250,71 @@ Get a single item from a conversation with the given IDs. - `"incomplete"` - - `Compaction object { id, encrypted_content, type, created_by }` - - A compaction item generated by the [`v1/responses/compact` API](/docs/api-reference/responses/compact). + - `Program object { id, call_id, code, 2 more }` - `id: string` - The unique ID of the compaction item. + The unique ID of the program item. - - `encrypted_content: string` + - `call_id: string` - The encrypted content that was produced by compaction. + The stable call ID of the program item. - - `type: "compaction"` + - `code: string` + + The JavaScript source executed by programmatic tool calling. + + - `fingerprint: string` + + Opaque program replay fingerprint that must be round-tripped. + + - `type: "program"` + + The type of the item. Always `program`. + + - `"program"` + + - `ProgramOutput object { id, call_id, result, 2 more }` + + - `id: string` + + The unique ID of the program output item. + + - `call_id: string` + + The call ID of the program item. + + - `result: string` + + The result produced by the program item. + + - `status: "completed" or "incomplete"` + + The terminal status of the program output item. + + - `"completed"` + + - `"incomplete"` + + - `type: "program_output"` + + The type of the item. Always `program_output`. + + - `"program_output"` + + - `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). + + - `id: string` + + The unique ID of the compaction item. + + - `encrypted_content: string` + + The encrypted content that was produced by compaction. + + - `type: "compaction"` The type of the item. Always `compaction`. @@ -18388,7 +21479,7 @@ Get a single item from a conversation with the given IDs. - `"incomplete"` - - `ShellCall object { id, action, call_id, 4 more }` + - `ShellCall object { id, action, call_id, 5 more }` A tool call that executes one or more shell commands in a managed environment. @@ -18456,11 +21547,31 @@ Get a single item from a conversation with the given IDs. - `"shell_call"` + - `caller: optional object { type } or object { caller_id, type }` + + The execution context that produced this tool call. + + - `Direct object { type }` + + - `type: "direct"` + + - `"direct"` + + - `Program object { caller_id, type }` + + - `caller_id: string` + + The call ID of the program item that produced this tool call. + + - `type: "program"` + + - `"program"` + - `created_by: optional string` The ID of the entity that created this tool call. - - `ShellCallOutput object { id, call_id, max_output_length, 4 more }` + - `ShellCallOutput object { id, call_id, max_output_length, 5 more }` The output of a shell tool call that was emitted. @@ -18536,11 +21647,31 @@ Get a single item from a conversation with the given IDs. - `"shell_call_output"` + - `caller: optional object { type } or object { caller_id, type }` + + The execution context that produced this tool call. + + - `Direct object { type }` + + - `type: "direct"` + + - `"direct"` + + - `Program object { caller_id, type }` + + - `caller_id: string` + + The call ID of the program item that produced this tool call. + + - `type: "program"` + + - `"program"` + - `created_by: optional string` The identifier of the actor that created the item. - - `ApplyPatchCall object { id, call_id, operation, 3 more }` + - `ApplyPatchCall object { id, call_id, operation, 4 more }` A tool call that applies file diffs by creating, deleting, or updating files. @@ -18620,11 +21751,31 @@ Get a single item from a conversation with the given IDs. - `"apply_patch_call"` + - `caller: optional object { type } or object { caller_id, type }` + + The execution context that produced this tool call. + + - `Direct object { type }` + + - `type: "direct"` + + - `"direct"` + + - `Program object { caller_id, type }` + + - `caller_id: string` + + The call ID of the program item that produced this tool call. + + - `type: "program"` + + - `"program"` + - `created_by: optional string` The ID of the entity that created this tool call. - - `ApplyPatchCallOutput object { id, call_id, status, 3 more }` + - `ApplyPatchCallOutput object { id, call_id, status, 4 more }` The output emitted by an apply patch tool call. @@ -18650,6 +21801,26 @@ Get a single item from a conversation with the given IDs. - `"apply_patch_call_output"` + - `caller: optional object { type } or object { caller_id, type }` + + The execution context that produced this tool call. + + - `Direct object { type }` + + - `type: "direct"` + + - `"direct"` + + - `Program object { caller_id, type }` + + - `caller_id: string` + + The call ID of the program item that produced this tool call. + + - `type: "program"` + + - `"program"` + - `created_by: optional string` The ID of the entity that created this tool call output. @@ -18805,7 +21976,7 @@ Get a single item from a conversation with the given IDs. - `"failed"` - - `CustomToolCall object { call_id, input, name, 3 more }` + - `CustomToolCall object { call_id, input, name, 4 more }` A call to a custom tool created by the model. @@ -18831,11 +22002,31 @@ Get a single item from a conversation with the given IDs. The unique ID of the custom tool call in the OpenAI platform. + - `caller: optional object { type } or object { caller_id, type }` + + The execution context that produced this tool call. + + - `Direct object { type }` + + - `type: "direct"` + + - `"direct"` + + - `Program object { caller_id, type }` + + - `caller_id: string` + + The call ID of the program item that produced this tool call. + + - `type: "program"` + + - `"program"` + - `namespace: optional string` The namespace of the custom tool being called. - - `CustomToolCallOutput object { call_id, output, type, id }` + - `CustomToolCallOutput object { call_id, output, type, 2 more }` The output of a custom tool call from your code, being sent back to the model. @@ -18856,15 +22047,15 @@ Get a single item from a conversation with the given IDs. Text, image, or file output of the custom tool call. - - `ResponseInputText object { text, type }` + - `ResponseInputText object { text, type, prompt_cache_breakpoint }` A text input to the model. - - `ResponseInputImage object { detail, type, file_id, image_url }` + - `ResponseInputImage object { detail, type, file_id, 2 more }` - An image input to the model. Learn about [image inputs](/docs/guides/vision). + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - `ResponseInputFile object { type, detail, file_data, 3 more }` + - `ResponseInputFile object { type, detail, file_data, 4 more }` A file input to the model. @@ -18878,6 +22069,30 @@ Get a single item from a conversation with the given IDs. 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. + + - `Direct object { type }` + + - `type: "direct"` + + The caller type. Always `direct`. + + - `"direct"` + + - `Program object { caller_id, type }` + + - `caller_id: string` + + The call ID of the program item that produced this tool call. + + - `type: "program"` + + The caller type. Always `program`. + + - `"program"` + ### Example ```http @@ -18893,7 +22108,10 @@ curl https://api.openai.com/v1/conversations/$CONVERSATION_ID/items/$ITEM_ID \ "content": [ { "text": "text", - "type": "input_text" + "type": "input_text", + "prompt_cache_breakpoint": { + "mode": "explicit" + } } ], "role": "unknown", @@ -18928,7 +22146,7 @@ curl https://api.openai.com/v1/conversations/conv_123/items/msg_abc \ **delete** `/conversations/{conversation_id}/items/{item_id}` -Delete an item from a conversation with the given IDs. +Delete an item ### Path Parameters @@ -19000,9 +22218,9 @@ curl -X DELETE https://api.openai.com/v1/conversations/conv_123/items/msg_abc \ ### Conversation Item -- `ConversationItem = Message or object { id, arguments, call_id, 5 more } or object { id, call_id, output, 3 more } or 23 more` +- `ConversationItem = Message or object { id, arguments, call_id, 6 more } or object { id, call_id, output, 4 more } or 25 more` - A single item within a conversation. The set of possible types are the same as the `output` type of a [Response object](/docs/api-reference/responses/object#responses/object-output). + A single item within a conversation. The set of possible types are the same as the `output` type of a [Response object](https://platform.openai.com/docs/api-reference/responses/object#responses/object-output). - `Message object { id, content, role, 3 more }` @@ -19016,7 +22234,7 @@ curl -X DELETE https://api.openai.com/v1/conversations/conv_123/items/msg_abc \ The content of the message - - `ResponseInputText object { text, type }` + - `ResponseInputText object { text, type, prompt_cache_breakpoint }` A text input to the model. @@ -19030,7 +22248,17 @@ curl -X DELETE https://api.openai.com/v1/conversations/conv_123/items/msg_abc \ - `"input_text"` - - `ResponseOutputText object { annotations, logprobs, text, type }` + - `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 }` A text output from the model. @@ -19134,15 +22362,17 @@ curl -X DELETE https://api.openai.com/v1/conversations/conv_123/items/msg_abc \ - `"file_path"` - - `logprobs: array of object { token, bytes, logprob, top_logprobs }` + - `text: string` - - `token: string` + The text output from the model. - - `bytes: array of number` + - `type: "output_text"` - - `logprob: number` + The type of the output text. Always `output_text`. - - `top_logprobs: array of object { token, bytes, logprob }` + - `"output_text"` + + - `logprobs: optional array of object { token, bytes, logprob, top_logprobs }` - `token: string` @@ -19150,15 +22380,13 @@ curl -X DELETE https://api.openai.com/v1/conversations/conv_123/items/msg_abc \ - `logprob: number` - - `text: string` - - The text output from the model. + - `top_logprobs: array of object { token, bytes, logprob }` - - `type: "output_text"` + - `token: string` - The type of the output text. Always `output_text`. + - `bytes: array of number` - - `"output_text"` + - `logprob: number` - `TextContent object { text, type }` @@ -19212,9 +22440,9 @@ curl -X DELETE https://api.openai.com/v1/conversations/conv_123/items/msg_abc \ - `"refusal"` - - `ResponseInputImage object { detail, type, file_id, image_url }` + - `ResponseInputImage object { detail, type, file_id, 2 more }` - An image input to the model. Learn about [image inputs](/docs/guides/vision). + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - `detail: "low" or "high" or "auto" or "original"` @@ -19242,7 +22470,17 @@ curl -X DELETE https://api.openai.com/v1/conversations/conv_123/items/msg_abc \ The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - - `ComputerScreenshotContent object { detail, file_id, image_url, type }` + - `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"` + + - `ComputerScreenshotContent object { detail, file_id, image_url, 2 more }` A screenshot of a computer. @@ -19272,7 +22510,17 @@ curl -X DELETE https://api.openai.com/v1/conversations/conv_123/items/msg_abc \ - `"computer_screenshot"` - - `ResponseInputFile object { type, detail, file_data, 3 more }` + - `prompt_cache_breakpoint: optional object { mode }` + + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + + - `mode: "explicit"` + + The breakpoint mode. Always `explicit`. + + - `"explicit"` + + - `ResponseInputFile object { type, detail, file_data, 4 more }` A file input to the model. @@ -19282,9 +22530,11 @@ curl -X DELETE https://api.openai.com/v1/conversations/conv_123/items/msg_abc \ - `"input_file"` - - `detail: optional "low" or "high"` + - `detail: optional "auto" or "low" or "high"` - The detail level of the file to be sent to the model. Use `low` for the default rendering behavior, or `high` to render the file at higher quality. Defaults to `low`. + The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. + + - `"auto"` - `"low"` @@ -19306,6 +22556,16 @@ curl -X DELETE https://api.openai.com/v1/conversations/conv_123/items/msg_abc \ The name of the file to be sent to the model. + - `prompt_cache_breakpoint: optional object { mode }` + + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + + - `mode: "explicit"` + + The breakpoint mode. Always `explicit`. + + - `"explicit"` + - `role: "unknown" or "user" or "assistant" or 5 more` The role of the message. One of `unknown`, `user`, `assistant`, `system`, `critic`, `discriminator`, `developer`, or `tool`. @@ -19350,7 +22610,7 @@ curl -X DELETE https://api.openai.com/v1/conversations/conv_123/items/msg_abc \ - `"final_answer"` - - `FunctionCall object { id, arguments, call_id, 5 more }` + - `FunctionCall object { id, arguments, call_id, 6 more }` - `id: string` @@ -19385,6 +22645,26 @@ curl -X DELETE https://api.openai.com/v1/conversations/conv_123/items/msg_abc \ - `"function_call"` + - `caller: optional object { type } or object { caller_id, type }` + + The execution context that produced this tool call. + + - `Direct object { type }` + + - `type: "direct"` + + - `"direct"` + + - `Program object { caller_id, type }` + + - `caller_id: string` + + The call ID of the program item that produced this tool call. + + - `type: "program"` + + - `"program"` + - `created_by: optional string` The identifier of the actor that created the item. @@ -19393,7 +22673,7 @@ curl -X DELETE https://api.openai.com/v1/conversations/conv_123/items/msg_abc \ The namespace of the function to run. - - `FunctionCallOutput object { id, call_id, output, 3 more }` + - `FunctionCallOutput object { id, call_id, output, 4 more }` - `id: string` @@ -19416,15 +22696,15 @@ curl -X DELETE https://api.openai.com/v1/conversations/conv_123/items/msg_abc \ Text, image, or file output of the function call. - - `ResponseInputText object { text, type }` + - `ResponseInputText object { text, type, prompt_cache_breakpoint }` A text input to the model. - - `ResponseInputImage object { detail, type, file_id, image_url }` + - `ResponseInputImage object { detail, type, file_id, 2 more }` - An image input to the model. Learn about [image inputs](/docs/guides/vision). + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - `ResponseInputFile object { type, detail, file_data, 3 more }` + - `ResponseInputFile object { type, detail, file_data, 4 more }` A file input to the model. @@ -19445,6 +22725,30 @@ curl -X DELETE https://api.openai.com/v1/conversations/conv_123/items/msg_abc \ - `"function_call_output"` + - `caller: optional object { type } or object { caller_id, type }` + + The execution context that produced this tool call. + + - `Direct object { type }` + + - `type: "direct"` + + The caller type. Always `direct`. + + - `"direct"` + + - `Program object { caller_id, type }` + + - `caller_id: string` + + The call ID of the program item that produced this tool call. + + - `type: "program"` + + The caller type. Always `program`. + + - `"program"` + - `created_by: optional string` The identifier of the actor that created the item. @@ -19452,7 +22756,7 @@ curl -X DELETE https://api.openai.com/v1/conversations/conv_123/items/msg_abc \ - `FileSearchCall object { id, queries, status, 2 more }` The results of a file search tool call. See the - [file search guide](/docs/guides/tools-file-search) for more information. + [file search guide](https://platform.openai.com/docs/guides/tools-file-search) for more information. - `id: string` @@ -19520,7 +22824,7 @@ curl -X DELETE https://api.openai.com/v1/conversations/conv_123/items/msg_abc \ - `WebSearchCall object { id, action, status, type }` The results of a web search tool call. See the - [web search guide](/docs/guides/tools-web-search) for more information. + [web search guide](https://platform.openai.com/docs/guides/tools-web-search) for more information. - `id: string` @@ -19646,7 +22950,7 @@ curl -X DELETE https://api.openai.com/v1/conversations/conv_123/items/msg_abc \ - `ComputerCall object { id, call_id, pending_safety_checks, 4 more }` A tool call to a computer use tool. See the - [computer use guide](/docs/guides/tools-computer-use) for more information. + [computer use guide](https://platform.openai.com/docs/guides/tools-computer-use) for more information. - `id: string` @@ -19689,7 +22993,7 @@ curl -X DELETE https://api.openai.com/v1/conversations/conv_123/items/msg_abc \ - `"computer_call"` - - `action: optional ComputerAction` + - `action: optional object { button, type, x, 2 more } or object { keys, type, x, y } or object { path, type, keys } or 6 more` A click action. @@ -19893,92 +23197,247 @@ curl -X DELETE https://api.openai.com/v1/conversations/conv_123/items/msg_abc \ A click action. - - `DoubleClick object { keys, type, x, y }` + - `button: "left" or "right" or "wheel" or 2 more` - A double click action. + Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. - - `Drag object { path, type, keys }` + - `"left"` - A drag action. + - `"right"` - - `Keypress object { keys, type }` + - `"wheel"` - A collection of keypresses the model would like to perform. + - `"back"` - - `Move object { type, x, y, keys }` + - `"forward"` - A mouse move action. + - `type: "click"` - - `Screenshot object { type }` + Specifies the event type. For a click action, this property is always `click`. - A screenshot action. + - `"click"` - - `Scroll object { scroll_x, scroll_y, type, 3 more }` + - `x: number` - A scroll action. + The x-coordinate where the click occurred. - - `Type object { text, type }` + - `y: number` - An action to type in text. + The y-coordinate where the click occurred. - - `Wait object { type }` + - `keys: optional array of string` - A wait action. + The keys being held while clicking. - - `ComputerCallOutput object { id, call_id, output, 4 more }` + - `DoubleClick object { keys, type, x, y }` - - `id: string` + A double click action. - The unique ID of the computer call tool output. + - `keys: array of string` - - `call_id: string` + The keys being held while double-clicking. - The ID of the computer tool call that produced the output. + - `type: "double_click"` - - `output: ResponseComputerToolCallOutputScreenshot` + Specifies the event type. For a double click action, this property is always set to `double_click`. - A computer screenshot image used with the computer use tool. + - `"double_click"` - - `type: "computer_screenshot"` + - `x: number` - Specifies the event type. For a computer screenshot, this property is - always set to `computer_screenshot`. + The x-coordinate where the double click occurred. - - `"computer_screenshot"` + - `y: number` - - `file_id: optional string` + The y-coordinate where the double click occurred. - The identifier of an uploaded file that contains the screenshot. + - `Drag object { path, type, keys }` - - `image_url: optional string` + A drag action. - The URL of the screenshot image. + - `path: array of object { x, y }` - - `status: "completed" or "incomplete" or "failed" or "in_progress"` + An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg - The status of the message input. One of `in_progress`, `completed`, or - `incomplete`. Populated when input items are returned via API. + ``` + [ + { x: 100, y: 200 }, + { x: 200, y: 300 } + ] + ``` - - `"completed"` + - `x: number` - - `"incomplete"` + The x-coordinate. - - `"failed"` + - `y: number` - - `"in_progress"` + The y-coordinate. - - `type: "computer_call_output"` + - `type: "drag"` - The type of the computer tool call output. Always `computer_call_output`. + Specifies the event type. For a drag action, this property is always set to `drag`. - - `"computer_call_output"` + - `"drag"` - - `acknowledged_safety_checks: optional array of object { id, code, message }` + - `keys: optional array of string` - The safety checks reported by the API that have been acknowledged by the - developer. + The keys being held while dragging the mouse. - - `id: string` + - `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 { id, call_id, output, 4 more }` + + - `id: string` + + The unique ID of the computer call tool output. + + - `call_id: string` + + The ID of the computer tool call that produced the output. + + - `output: ResponseComputerToolCallOutputScreenshot` + + A computer screenshot image used with the computer use tool. + + - `type: "computer_screenshot"` + + Specifies the event type. For a computer screenshot, this property is + always set to `computer_screenshot`. + + - `"computer_screenshot"` + + - `file_id: optional string` + + The identifier of an uploaded file that contains the screenshot. + + - `image_url: optional string` + + The URL of the screenshot image. + + - `status: "completed" or "incomplete" or "failed" or "in_progress"` + + The status of the message input. One of `in_progress`, `completed`, or + `incomplete`. Populated when input items are returned via API. + + - `"completed"` + + - `"incomplete"` + + - `"failed"` + + - `"in_progress"` + + - `type: "computer_call_output"` + + The type of the computer tool call output. Always `computer_call_output`. + + - `"computer_call_output"` + + - `acknowledged_safety_checks: optional array of object { id, code, message }` + + The safety checks reported by the API that have been acknowledged by the + developer. + + - `id: string` The ID of the pending safety check. @@ -20064,11 +23523,11 @@ curl -X DELETE https://api.openai.com/v1/conversations/conv_123/items/msg_abc \ - `"incomplete"` - - `tools: array of object { name, parameters, strict, 3 more } or object { type, vector_store_ids, filters, 2 more } or object { type } or 12 more` + - `tools: array of object { name, parameters, strict, 5 more } or object { type, vector_store_ids, filters, 2 more } or object { type } or 13 more` The loaded tool definitions returned by tool search. - - `Function object { name, parameters, strict, 3 more }` + - `Function object { name, parameters, strict, 5 more }` Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). @@ -20082,7 +23541,7 @@ curl -X DELETE https://api.openai.com/v1/conversations/conv_123/items/msg_abc \ - `strict: boolean` - Whether to enforce strict parameter validation. Default `true`. + Whether strict parameter validation is enforced for this function tool. - `type: "function"` @@ -20090,6 +23549,14 @@ curl -X DELETE https://api.openai.com/v1/conversations/conv_123/items/msg_abc \ - `"function"` + - `allowed_callers: optional array of "direct" or "programmatic"` + + The tool invocation context(s). + + - `"direct"` + + - `"programmatic"` + - `defer_loading: optional boolean` Whether this function is deferred and loaded via tool search. @@ -20098,6 +23565,10 @@ curl -X DELETE https://api.openai.com/v1/conversations/conv_123/items/msg_abc \ 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). @@ -20268,7 +23739,7 @@ curl -X DELETE https://api.openai.com/v1/conversations/conv_123/items/msg_abc \ - `WebSearch object { type, filters, search_context_size, user_location }` Search the Internet for sources related to the prompt. Learn more about the - [web search tool](/docs/guides/tools-web-search). + [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - `type: "web_search" or "web_search_2025_08_26"` @@ -20325,10 +23796,10 @@ curl -X DELETE https://api.openai.com/v1/conversations/conv_123/items/msg_abc \ - `"approximate"` - - `Mcp object { server_label, type, allowed_tools, 8 more }` + - `Mcp object { server_label, type, allowed_callers, 9 more }` Give the model access to additional tools via remote Model Context Protocol - (MCP) servers. [Learn more about MCP](/docs/guides/tools-remote-mcp). + (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). - `server_label: string` @@ -20340,6 +23811,14 @@ curl -X DELETE https://api.openai.com/v1/conversations/conv_123/items/msg_abc \ - `"mcp"` + - `allowed_callers: optional array of "direct" or "programmatic"` + + The tool invocation context(s). + + - `"direct"` + + - `"programmatic"` + - `allowed_tools: optional array of string or object { read_only, tool_names }` List of allowed tool names or a filter object. @@ -20372,7 +23851,7 @@ curl -X DELETE https://api.openai.com/v1/conversations/conv_123/items/msg_abc \ Identifier for service connectors, like those available in ChatGPT. One of `server_url`, `connector_id`, or `tunnel_id` must be provided. Learn more - about service connectors [here](/docs/guides/tools-remote-mcp#connectors). + about service connectors [here](https://platform.openai.com/docs/guides/tools-remote-mcp#connectors). Currently supported `connector_id` values are: @@ -20472,7 +23951,7 @@ curl -X DELETE https://api.openai.com/v1/conversations/conv_123/items/msg_abc \ The Secure MCP Tunnel ID to use instead of a direct server URL. One of `server_url`, `connector_id`, or `tunnel_id` must be provided. - - `CodeInterpreter object { container, type }` + - `CodeInterpreter object { container, type, allowed_callers }` A tool that runs Python code to help generate a response to a prompt. @@ -20558,6 +24037,22 @@ curl -X DELETE https://api.openai.com/v1/conversations/conv_123/items/msg_abc \ - `"code_interpreter"` + - `allowed_callers: optional array of "direct" or "programmatic"` + + The tool invocation context(s). + + - `"direct"` + + - `"programmatic"` + + - `ProgrammaticToolCalling object { type }` + + - `type: "programmatic_tool_calling"` + + The type of the tool. Always `programmatic_tool_calling`. + + - `"programmatic_tool_calling"` + - `ImageGeneration object { type, action, background, 9 more }` A tool that generates images using the GPT image models. @@ -20580,8 +24075,19 @@ curl -X DELETE https://api.openai.com/v1/conversations/conv_123/items/msg_abc \ - `background: optional "transparent" or "opaque" or "auto"` - Background type for the generated image. One of `transparent`, - `opaque`, or `auto`. Default: `auto`. + Allows to set transparency for the background of the generated image(s). + This parameter is only supported for GPT image models that support + transparent backgrounds. Must be one of `transparent`, `opaque`, or + `auto` (default value). When `auto` is used, the model will + automatically determine the best background for the image. + + `gpt-image-2` and `gpt-image-2-2026-04-21` do not support + transparent backgrounds. Requests with `background` set to + `transparent` will return an error for these models; use `opaque` or + `auto` instead. + + If `transparent`, the output format needs to support transparency, + so it should be set to either `png` (default value) or `webp`. - `"transparent"` @@ -20610,13 +24116,13 @@ curl -X DELETE https://api.openai.com/v1/conversations/conv_123/items/msg_abc \ Base64-encoded mask image. - - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` + - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-2" or 3 more` The image generation model to use. Default: `gpt-image-1`. - `string` - - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` + - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-2" or 3 more` The image generation model to use. Default: `gpt-image-1`. @@ -20624,8 +24130,14 @@ curl -X DELETE https://api.openai.com/v1/conversations/conv_123/items/msg_abc \ - `"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`. @@ -20694,7 +24206,7 @@ curl -X DELETE https://api.openai.com/v1/conversations/conv_123/items/msg_abc \ - `"local_shell"` - - `Shell object { type, environment }` + - `Shell object { type, allowed_callers, environment }` A tool that allows the model to execute shell commands. @@ -20704,6 +24216,14 @@ curl -X DELETE https://api.openai.com/v1/conversations/conv_123/items/msg_abc \ - `"shell"` + - `allowed_callers: optional array of "direct" or "programmatic"` + + The tool invocation context(s). + + - `"direct"` + + - `"programmatic"` + - `environment: optional ContainerAuto or LocalEnvironment or ContainerReference` - `ContainerAuto object { type, file_ids, memory_limit, 2 more }` @@ -20830,9 +24350,9 @@ curl -X DELETE https://api.openai.com/v1/conversations/conv_123/items/msg_abc \ - `"container_reference"` - - `Custom object { name, type, defer_loading, 2 more }` + - `Custom object { name, type, allowed_callers, 3 more }` - A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) - `name: string` @@ -20844,6 +24364,14 @@ curl -X DELETE https://api.openai.com/v1/conversations/conv_123/items/msg_abc \ - `"custom"` + - `allowed_callers: optional array of "direct" or "programmatic"` + + The tool invocation context(s). + + - `"direct"` + + - `"programmatic"` + - `defer_loading: optional boolean` Whether this tool should be deferred and discovered via tool search. @@ -20900,11 +24428,11 @@ curl -X DELETE https://api.openai.com/v1/conversations/conv_123/items/msg_abc \ The namespace name used in tool calls (for example, `crm`). - - `tools: array of object { name, type, defer_loading, 3 more } or object { name, type, defer_loading, 2 more }` + - `tools: array of object { name, type, allowed_callers, 5 more } or object { name, type, allowed_callers, 3 more }` The function/custom tools available inside this namespace. - - `Function object { name, type, defer_loading, 3 more }` + - `Function object { name, type, allowed_callers, 5 more }` - `name: string` @@ -20912,19 +24440,33 @@ curl -X DELETE https://api.openai.com/v1/conversations/conv_123/items/msg_abc \ - `"function"` + - `allowed_callers: optional array of "direct" or "programmatic"` + + The tool invocation context(s). + + - `"direct"` + + - `"programmatic"` + - `defer_loading: optional boolean` Whether this function should be deferred and discovered via tool search. - `description: optional string` + - `output_schema: optional map[unknown]` + + A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. + - `parameters: optional unknown` - `strict: optional boolean` - - `Custom object { name, type, defer_loading, 2 more }` + Whether to enforce strict parameter validation. If omitted, Responses attempts to use strict validation when the schema is compatible, and falls back to non-strict validation otherwise. + + - `Custom object { name, type, allowed_callers, 3 more }` - A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) - `name: string` @@ -20936,6 +24478,14 @@ curl -X DELETE https://api.openai.com/v1/conversations/conv_123/items/msg_abc \ - `"custom"` + - `allowed_callers: optional array of "direct" or "programmatic"` + + The tool invocation context(s). + + - `"direct"` + + - `"programmatic"` + - `defer_loading: optional boolean` Whether this tool should be deferred and discovered via tool search. @@ -21034,7 +24584,7 @@ curl -X DELETE https://api.openai.com/v1/conversations/conv_123/items/msg_abc \ The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - - `ApplyPatch object { type }` + - `ApplyPatch object { type, allowed_callers }` Allows the assistant to create, delete, or update files using unified diffs. @@ -21044,6 +24594,14 @@ curl -X DELETE https://api.openai.com/v1/conversations/conv_123/items/msg_abc \ - `"apply_patch"` + - `allowed_callers: optional array of "direct" or "programmatic"` + + The tool invocation context(s). + + - `"direct"` + + - `"programmatic"` + - `type: "tool_search_output"` The type of the item. Always `tool_search_output`. @@ -21080,11 +24638,11 @@ curl -X DELETE https://api.openai.com/v1/conversations/conv_123/items/msg_abc \ - `"tool"` - - `tools: array of object { name, parameters, strict, 3 more } or object { type, vector_store_ids, filters, 2 more } or object { type } or 12 more` + - `tools: array of object { name, parameters, strict, 5 more } or object { type, vector_store_ids, filters, 2 more } or object { type } or 13 more` The additional tool definitions made available at this item. - - `Function object { name, parameters, strict, 3 more }` + - `Function object { name, parameters, strict, 5 more }` Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). @@ -21098,7 +24656,7 @@ curl -X DELETE https://api.openai.com/v1/conversations/conv_123/items/msg_abc \ - `strict: boolean` - Whether to enforce strict parameter validation. Default `true`. + Whether strict parameter validation is enforced for this function tool. - `type: "function"` @@ -21106,6 +24664,14 @@ curl -X DELETE https://api.openai.com/v1/conversations/conv_123/items/msg_abc \ - `"function"` + - `allowed_callers: optional array of "direct" or "programmatic"` + + The tool invocation context(s). + + - `"direct"` + + - `"programmatic"` + - `defer_loading: optional boolean` Whether this function is deferred and loaded via tool search. @@ -21114,6 +24680,10 @@ curl -X DELETE https://api.openai.com/v1/conversations/conv_123/items/msg_abc \ 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). @@ -21217,7 +24787,7 @@ curl -X DELETE https://api.openai.com/v1/conversations/conv_123/items/msg_abc \ - `WebSearch object { type, filters, search_context_size, user_location }` Search the Internet for sources related to the prompt. Learn more about the - [web search tool](/docs/guides/tools-web-search). + [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - `type: "web_search" or "web_search_2025_08_26"` @@ -21274,10 +24844,10 @@ curl -X DELETE https://api.openai.com/v1/conversations/conv_123/items/msg_abc \ - `"approximate"` - - `Mcp object { server_label, type, allowed_tools, 8 more }` + - `Mcp object { server_label, type, allowed_callers, 9 more }` Give the model access to additional tools via remote Model Context Protocol - (MCP) servers. [Learn more about MCP](/docs/guides/tools-remote-mcp). + (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). - `server_label: string` @@ -21289,6 +24859,14 @@ curl -X DELETE https://api.openai.com/v1/conversations/conv_123/items/msg_abc \ - `"mcp"` + - `allowed_callers: optional array of "direct" or "programmatic"` + + The tool invocation context(s). + + - `"direct"` + + - `"programmatic"` + - `allowed_tools: optional array of string or object { read_only, tool_names }` List of allowed tool names or a filter object. @@ -21321,7 +24899,7 @@ curl -X DELETE https://api.openai.com/v1/conversations/conv_123/items/msg_abc \ Identifier for service connectors, like those available in ChatGPT. One of `server_url`, `connector_id`, or `tunnel_id` must be provided. Learn more - about service connectors [here](/docs/guides/tools-remote-mcp#connectors). + about service connectors [here](https://platform.openai.com/docs/guides/tools-remote-mcp#connectors). Currently supported `connector_id` values are: @@ -21421,7 +24999,7 @@ curl -X DELETE https://api.openai.com/v1/conversations/conv_123/items/msg_abc \ The Secure MCP Tunnel ID to use instead of a direct server URL. One of `server_url`, `connector_id`, or `tunnel_id` must be provided. - - `CodeInterpreter object { container, type }` + - `CodeInterpreter object { container, type, allowed_callers }` A tool that runs Python code to help generate a response to a prompt. @@ -21475,6 +25053,22 @@ curl -X DELETE https://api.openai.com/v1/conversations/conv_123/items/msg_abc \ - `"code_interpreter"` + - `allowed_callers: optional array of "direct" or "programmatic"` + + The tool invocation context(s). + + - `"direct"` + + - `"programmatic"` + + - `ProgrammaticToolCalling object { type }` + + - `type: "programmatic_tool_calling"` + + The type of the tool. Always `programmatic_tool_calling`. + + - `"programmatic_tool_calling"` + - `ImageGeneration object { type, action, background, 9 more }` A tool that generates images using the GPT image models. @@ -21497,8 +25091,19 @@ curl -X DELETE https://api.openai.com/v1/conversations/conv_123/items/msg_abc \ - `background: optional "transparent" or "opaque" or "auto"` - Background type for the generated image. One of `transparent`, - `opaque`, or `auto`. Default: `auto`. + Allows to set transparency for the background of the generated image(s). + This parameter is only supported for GPT image models that support + transparent backgrounds. Must be one of `transparent`, `opaque`, or + `auto` (default value). When `auto` is used, the model will + automatically determine the best background for the image. + + `gpt-image-2` and `gpt-image-2-2026-04-21` do not support + transparent backgrounds. Requests with `background` set to + `transparent` will return an error for these models; use `opaque` or + `auto` instead. + + If `transparent`, the output format needs to support transparency, + so it should be set to either `png` (default value) or `webp`. - `"transparent"` @@ -21527,13 +25132,13 @@ curl -X DELETE https://api.openai.com/v1/conversations/conv_123/items/msg_abc \ Base64-encoded mask image. - - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` + - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-2" or 3 more` The image generation model to use. Default: `gpt-image-1`. - `string` - - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` + - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-2" or 3 more` The image generation model to use. Default: `gpt-image-1`. @@ -21541,8 +25146,14 @@ curl -X DELETE https://api.openai.com/v1/conversations/conv_123/items/msg_abc \ - `"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`. @@ -21611,7 +25222,7 @@ curl -X DELETE https://api.openai.com/v1/conversations/conv_123/items/msg_abc \ - `"local_shell"` - - `Shell object { type, environment }` + - `Shell object { type, allowed_callers, environment }` A tool that allows the model to execute shell commands. @@ -21621,6 +25232,14 @@ curl -X DELETE https://api.openai.com/v1/conversations/conv_123/items/msg_abc \ - `"shell"` + - `allowed_callers: optional array of "direct" or "programmatic"` + + The tool invocation context(s). + + - `"direct"` + + - `"programmatic"` + - `environment: optional ContainerAuto or LocalEnvironment or ContainerReference` - `ContainerAuto object { type, file_ids, memory_limit, 2 more }` @@ -21629,9 +25248,9 @@ curl -X DELETE https://api.openai.com/v1/conversations/conv_123/items/msg_abc \ - `ContainerReference object { container_id, type }` - - `Custom object { name, type, defer_loading, 2 more }` + - `Custom object { name, type, allowed_callers, 3 more }` - A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) - `name: string` @@ -21643,6 +25262,14 @@ curl -X DELETE https://api.openai.com/v1/conversations/conv_123/items/msg_abc \ - `"custom"` + - `allowed_callers: optional array of "direct" or "programmatic"` + + The tool invocation context(s). + + - `"direct"` + + - `"programmatic"` + - `defer_loading: optional boolean` Whether this tool should be deferred and discovered via tool search. @@ -21667,11 +25294,11 @@ curl -X DELETE https://api.openai.com/v1/conversations/conv_123/items/msg_abc \ The namespace name used in tool calls (for example, `crm`). - - `tools: array of object { name, type, defer_loading, 3 more } or object { name, type, defer_loading, 2 more }` + - `tools: array of object { name, type, allowed_callers, 5 more } or object { name, type, allowed_callers, 3 more }` The function/custom tools available inside this namespace. - - `Function object { name, type, defer_loading, 3 more }` + - `Function object { name, type, allowed_callers, 5 more }` - `name: string` @@ -21679,19 +25306,33 @@ curl -X DELETE https://api.openai.com/v1/conversations/conv_123/items/msg_abc \ - `"function"` + - `allowed_callers: optional array of "direct" or "programmatic"` + + The tool invocation context(s). + + - `"direct"` + + - `"programmatic"` + - `defer_loading: optional boolean` Whether this function should be deferred and discovered via tool search. - `description: optional string` + - `output_schema: optional map[unknown]` + + A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. + - `parameters: optional unknown` - `strict: optional boolean` - - `Custom object { name, type, defer_loading, 2 more }` + Whether to enforce strict parameter validation. If omitted, Responses attempts to use strict validation when the schema is compatible, and falls back to non-strict validation otherwise. + + - `Custom object { name, type, allowed_callers, 3 more }` - A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) - `name: string` @@ -21703,6 +25344,14 @@ curl -X DELETE https://api.openai.com/v1/conversations/conv_123/items/msg_abc \ - `"custom"` + - `allowed_callers: optional array of "direct" or "programmatic"` + + The tool invocation context(s). + + - `"direct"` + + - `"programmatic"` + - `defer_loading: optional boolean` Whether this tool should be deferred and discovered via tool search. @@ -21801,7 +25450,7 @@ curl -X DELETE https://api.openai.com/v1/conversations/conv_123/items/msg_abc \ The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - - `ApplyPatch object { type }` + - `ApplyPatch object { type, allowed_callers }` Allows the assistant to create, delete, or update files using unified diffs. @@ -21811,6 +25460,14 @@ curl -X DELETE https://api.openai.com/v1/conversations/conv_123/items/msg_abc \ - `"apply_patch"` + - `allowed_callers: optional array of "direct" or "programmatic"` + + The tool invocation context(s). + + - `"direct"` + + - `"programmatic"` + - `type: "additional_tools"` The type of the item. Always `additional_tools`. @@ -21822,13 +25479,13 @@ curl -X DELETE https://api.openai.com/v1/conversations/conv_123/items/msg_abc \ A description of the chain of thought used by a reasoning model while generating a response. Be sure to include these items in your `input` to the Responses API for subsequent turns of a conversation if you are manually - [managing context](/docs/guides/conversation-state). + [managing context](https://platform.openai.com/docs/guides/conversation-state). - `id: string` The unique identifier of the reasoning content. - - `summary: array of SummaryTextContent` + - `summary: array of object { text, type }` Reasoning summary content. @@ -21840,6 +25497,8 @@ curl -X DELETE https://api.openai.com/v1/conversations/conv_123/items/msg_abc \ The type of the object. Always `summary_text`. + - `"summary_text"` + - `type: "reasoning"` The type of the object. Always `reasoning`. @@ -21876,19 +25535,71 @@ curl -X DELETE https://api.openai.com/v1/conversations/conv_123/items/msg_abc \ - `"incomplete"` - - `Compaction object { id, encrypted_content, type, created_by }` - - A compaction item generated by the [`v1/responses/compact` API](/docs/api-reference/responses/compact). + - `Program object { id, call_id, code, 2 more }` - `id: string` - The unique ID of the compaction item. + The unique ID of the program item. - - `encrypted_content: string` + - `call_id: string` - The encrypted content that was produced by compaction. + The stable call ID of the program item. - - `type: "compaction"` + - `code: string` + + The JavaScript source executed by programmatic tool calling. + + - `fingerprint: string` + + Opaque program replay fingerprint that must be round-tripped. + + - `type: "program"` + + The type of the item. Always `program`. + + - `"program"` + + - `ProgramOutput object { id, call_id, result, 2 more }` + + - `id: string` + + The unique ID of the program output item. + + - `call_id: string` + + The call ID of the program item. + + - `result: string` + + The result produced by the program item. + + - `status: "completed" or "incomplete"` + + The terminal status of the program output item. + + - `"completed"` + + - `"incomplete"` + + - `type: "program_output"` + + The type of the item. Always `program_output`. + + - `"program_output"` + + - `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). + + - `id: string` + + The unique ID of the compaction item. + + - `encrypted_content: string` + + The encrypted content that was produced by compaction. + + - `type: "compaction"` The type of the item. Always `compaction`. @@ -22053,7 +25764,7 @@ curl -X DELETE https://api.openai.com/v1/conversations/conv_123/items/msg_abc \ - `"incomplete"` - - `ShellCall object { id, action, call_id, 4 more }` + - `ShellCall object { id, action, call_id, 5 more }` A tool call that executes one or more shell commands in a managed environment. @@ -22121,11 +25832,31 @@ curl -X DELETE https://api.openai.com/v1/conversations/conv_123/items/msg_abc \ - `"shell_call"` + - `caller: optional object { type } or object { caller_id, type }` + + The execution context that produced this tool call. + + - `Direct object { type }` + + - `type: "direct"` + + - `"direct"` + + - `Program object { caller_id, type }` + + - `caller_id: string` + + The call ID of the program item that produced this tool call. + + - `type: "program"` + + - `"program"` + - `created_by: optional string` The ID of the entity that created this tool call. - - `ShellCallOutput object { id, call_id, max_output_length, 4 more }` + - `ShellCallOutput object { id, call_id, max_output_length, 5 more }` The output of a shell tool call that was emitted. @@ -22201,11 +25932,31 @@ curl -X DELETE https://api.openai.com/v1/conversations/conv_123/items/msg_abc \ - `"shell_call_output"` + - `caller: optional object { type } or object { caller_id, type }` + + The execution context that produced this tool call. + + - `Direct object { type }` + + - `type: "direct"` + + - `"direct"` + + - `Program object { caller_id, type }` + + - `caller_id: string` + + The call ID of the program item that produced this tool call. + + - `type: "program"` + + - `"program"` + - `created_by: optional string` The identifier of the actor that created the item. - - `ApplyPatchCall object { id, call_id, operation, 3 more }` + - `ApplyPatchCall object { id, call_id, operation, 4 more }` A tool call that applies file diffs by creating, deleting, or updating files. @@ -22285,11 +26036,31 @@ curl -X DELETE https://api.openai.com/v1/conversations/conv_123/items/msg_abc \ - `"apply_patch_call"` + - `caller: optional object { type } or object { caller_id, type }` + + The execution context that produced this tool call. + + - `Direct object { type }` + + - `type: "direct"` + + - `"direct"` + + - `Program object { caller_id, type }` + + - `caller_id: string` + + The call ID of the program item that produced this tool call. + + - `type: "program"` + + - `"program"` + - `created_by: optional string` The ID of the entity that created this tool call. - - `ApplyPatchCallOutput object { id, call_id, status, 3 more }` + - `ApplyPatchCallOutput object { id, call_id, status, 4 more }` The output emitted by an apply patch tool call. @@ -22315,6 +26086,26 @@ curl -X DELETE https://api.openai.com/v1/conversations/conv_123/items/msg_abc \ - `"apply_patch_call_output"` + - `caller: optional object { type } or object { caller_id, type }` + + The execution context that produced this tool call. + + - `Direct object { type }` + + - `type: "direct"` + + - `"direct"` + + - `Program object { caller_id, type }` + + - `caller_id: string` + + The call ID of the program item that produced this tool call. + + - `type: "program"` + + - `"program"` + - `created_by: optional string` The ID of the entity that created this tool call output. @@ -22470,7 +26261,7 @@ curl -X DELETE https://api.openai.com/v1/conversations/conv_123/items/msg_abc \ - `"failed"` - - `CustomToolCall object { call_id, input, name, 3 more }` + - `CustomToolCall object { call_id, input, name, 4 more }` A call to a custom tool created by the model. @@ -22496,11 +26287,31 @@ curl -X DELETE https://api.openai.com/v1/conversations/conv_123/items/msg_abc \ The unique ID of the custom tool call in the OpenAI platform. + - `caller: optional object { type } or object { caller_id, type }` + + The execution context that produced this tool call. + + - `Direct object { type }` + + - `type: "direct"` + + - `"direct"` + + - `Program object { caller_id, type }` + + - `caller_id: string` + + The call ID of the program item that produced this tool call. + + - `type: "program"` + + - `"program"` + - `namespace: optional string` The namespace of the custom tool being called. - - `CustomToolCallOutput object { call_id, output, type, id }` + - `CustomToolCallOutput object { call_id, output, type, 2 more }` The output of a custom tool call from your code, being sent back to the model. @@ -22521,15 +26332,15 @@ curl -X DELETE https://api.openai.com/v1/conversations/conv_123/items/msg_abc \ Text, image, or file output of the custom tool call. - - `ResponseInputText object { text, type }` + - `ResponseInputText object { text, type, prompt_cache_breakpoint }` A text input to the model. - - `ResponseInputImage object { detail, type, file_id, image_url }` + - `ResponseInputImage object { detail, type, file_id, 2 more }` - An image input to the model. Learn about [image inputs](/docs/guides/vision). + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - `ResponseInputFile object { type, detail, file_data, 3 more }` + - `ResponseInputFile object { type, detail, file_data, 4 more }` A file input to the model. @@ -22543,6 +26354,30 @@ curl -X DELETE https://api.openai.com/v1/conversations/conv_123/items/msg_abc \ 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. + + - `Direct object { type }` + + - `type: "direct"` + + The caller type. Always `direct`. + + - `"direct"` + + - `Program object { caller_id, type }` + + - `caller_id: string` + + The call ID of the program item that produced this tool call. + + - `type: "program"` + + The caller type. Always `program`. + + - `"program"` + ### Conversation Item List - `ConversationItemList object { data, first_id, has_more, 2 more }` @@ -22565,7 +26400,7 @@ curl -X DELETE https://api.openai.com/v1/conversations/conv_123/items/msg_abc \ The content of the message - - `ResponseInputText object { text, type }` + - `ResponseInputText object { text, type, prompt_cache_breakpoint }` A text input to the model. @@ -22579,7 +26414,17 @@ curl -X DELETE https://api.openai.com/v1/conversations/conv_123/items/msg_abc \ - `"input_text"` - - `ResponseOutputText object { annotations, logprobs, text, type }` + - `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 }` A text output from the model. @@ -22683,15 +26528,17 @@ curl -X DELETE https://api.openai.com/v1/conversations/conv_123/items/msg_abc \ - `"file_path"` - - `logprobs: array of object { token, bytes, logprob, top_logprobs }` + - `text: string` - - `token: string` + The text output from the model. - - `bytes: array of number` + - `type: "output_text"` - - `logprob: number` + The type of the output text. Always `output_text`. - - `top_logprobs: array of object { token, bytes, logprob }` + - `"output_text"` + + - `logprobs: optional array of object { token, bytes, logprob, top_logprobs }` - `token: string` @@ -22699,15 +26546,13 @@ curl -X DELETE https://api.openai.com/v1/conversations/conv_123/items/msg_abc \ - `logprob: number` - - `text: string` - - The text output from the model. + - `top_logprobs: array of object { token, bytes, logprob }` - - `type: "output_text"` + - `token: string` - The type of the output text. Always `output_text`. + - `bytes: array of number` - - `"output_text"` + - `logprob: number` - `TextContent object { text, type }` @@ -22761,9 +26606,9 @@ curl -X DELETE https://api.openai.com/v1/conversations/conv_123/items/msg_abc \ - `"refusal"` - - `ResponseInputImage object { detail, type, file_id, image_url }` + - `ResponseInputImage object { detail, type, file_id, 2 more }` - An image input to the model. Learn about [image inputs](/docs/guides/vision). + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - `detail: "low" or "high" or "auto" or "original"` @@ -22791,7 +26636,17 @@ curl -X DELETE https://api.openai.com/v1/conversations/conv_123/items/msg_abc \ The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - - `ComputerScreenshotContent object { detail, file_id, image_url, type }` + - `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"` + + - `ComputerScreenshotContent object { detail, file_id, image_url, 2 more }` A screenshot of a computer. @@ -22821,7 +26676,17 @@ curl -X DELETE https://api.openai.com/v1/conversations/conv_123/items/msg_abc \ - `"computer_screenshot"` - - `ResponseInputFile object { type, detail, file_data, 3 more }` + - `prompt_cache_breakpoint: optional object { mode }` + + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + + - `mode: "explicit"` + + The breakpoint mode. Always `explicit`. + + - `"explicit"` + + - `ResponseInputFile object { type, detail, file_data, 4 more }` A file input to the model. @@ -22831,9 +26696,11 @@ curl -X DELETE https://api.openai.com/v1/conversations/conv_123/items/msg_abc \ - `"input_file"` - - `detail: optional "low" or "high"` + - `detail: optional "auto" or "low" or "high"` - The detail level of the file to be sent to the model. Use `low` for the default rendering behavior, or `high` to render the file at higher quality. Defaults to `low`. + The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. + + - `"auto"` - `"low"` @@ -22855,6 +26722,16 @@ curl -X DELETE https://api.openai.com/v1/conversations/conv_123/items/msg_abc \ The name of the file to be sent to the model. + - `prompt_cache_breakpoint: optional object { mode }` + + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + + - `mode: "explicit"` + + The breakpoint mode. Always `explicit`. + + - `"explicit"` + - `role: "unknown" or "user" or "assistant" or 5 more` The role of the message. One of `unknown`, `user`, `assistant`, `system`, `critic`, `discriminator`, `developer`, or `tool`. @@ -22899,7 +26776,7 @@ curl -X DELETE https://api.openai.com/v1/conversations/conv_123/items/msg_abc \ - `"final_answer"` - - `FunctionCall object { id, arguments, call_id, 5 more }` + - `FunctionCall object { id, arguments, call_id, 6 more }` - `id: string` @@ -22934,6 +26811,26 @@ curl -X DELETE https://api.openai.com/v1/conversations/conv_123/items/msg_abc \ - `"function_call"` + - `caller: optional object { type } or object { caller_id, type }` + + The execution context that produced this tool call. + + - `Direct object { type }` + + - `type: "direct"` + + - `"direct"` + + - `Program object { caller_id, type }` + + - `caller_id: string` + + The call ID of the program item that produced this tool call. + + - `type: "program"` + + - `"program"` + - `created_by: optional string` The identifier of the actor that created the item. @@ -22942,7 +26839,7 @@ curl -X DELETE https://api.openai.com/v1/conversations/conv_123/items/msg_abc \ The namespace of the function to run. - - `FunctionCallOutput object { id, call_id, output, 3 more }` + - `FunctionCallOutput object { id, call_id, output, 4 more }` - `id: string` @@ -22965,15 +26862,15 @@ curl -X DELETE https://api.openai.com/v1/conversations/conv_123/items/msg_abc \ Text, image, or file output of the function call. - - `ResponseInputText object { text, type }` + - `ResponseInputText object { text, type, prompt_cache_breakpoint }` A text input to the model. - - `ResponseInputImage object { detail, type, file_id, image_url }` + - `ResponseInputImage object { detail, type, file_id, 2 more }` - An image input to the model. Learn about [image inputs](/docs/guides/vision). + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - `ResponseInputFile object { type, detail, file_data, 3 more }` + - `ResponseInputFile object { type, detail, file_data, 4 more }` A file input to the model. @@ -22994,6 +26891,30 @@ curl -X DELETE https://api.openai.com/v1/conversations/conv_123/items/msg_abc \ - `"function_call_output"` + - `caller: optional object { type } or object { caller_id, type }` + + The execution context that produced this tool call. + + - `Direct object { type }` + + - `type: "direct"` + + The caller type. Always `direct`. + + - `"direct"` + + - `Program object { caller_id, type }` + + - `caller_id: string` + + The call ID of the program item that produced this tool call. + + - `type: "program"` + + The caller type. Always `program`. + + - `"program"` + - `created_by: optional string` The identifier of the actor that created the item. @@ -23001,7 +26922,7 @@ curl -X DELETE https://api.openai.com/v1/conversations/conv_123/items/msg_abc \ - `FileSearchCall object { id, queries, status, 2 more }` The results of a file search tool call. See the - [file search guide](/docs/guides/tools-file-search) for more information. + [file search guide](https://platform.openai.com/docs/guides/tools-file-search) for more information. - `id: string` @@ -23069,7 +26990,7 @@ curl -X DELETE https://api.openai.com/v1/conversations/conv_123/items/msg_abc \ - `WebSearchCall object { id, action, status, type }` The results of a web search tool call. See the - [web search guide](/docs/guides/tools-web-search) for more information. + [web search guide](https://platform.openai.com/docs/guides/tools-web-search) for more information. - `id: string` @@ -23195,7 +27116,7 @@ curl -X DELETE https://api.openai.com/v1/conversations/conv_123/items/msg_abc \ - `ComputerCall object { id, call_id, pending_safety_checks, 4 more }` A tool call to a computer use tool. See the - [computer use guide](/docs/guides/tools-computer-use) for more information. + [computer use guide](https://platform.openai.com/docs/guides/tools-computer-use) for more information. - `id: string` @@ -23217,30 +27138,226 @@ curl -X DELETE https://api.openai.com/v1/conversations/conv_123/items/msg_abc \ The type of the pending safety check. - - `message: optional string` + - `message: optional string` + + Details about the pending safety check. + + - `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: "computer_call"` + + The type of the computer call. Always `computer_call`. + + - `"computer_call"` + + - `action: optional object { button, type, x, 2 more } or object { keys, type, x, y } or object { path, type, keys } or 6 more` + + A click action. + + - `Click object { button, type, x, 2 more }` + + A click action. + + - `button: "left" or "right" or "wheel" or 2 more` + + Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. + + - `"left"` + + - `"right"` + + - `"wheel"` + + - `"back"` + + - `"forward"` + + - `type: "click"` + + Specifies the event type. For a click action, this property is always `click`. + + - `"click"` + + - `x: number` + + The x-coordinate where the click occurred. + + - `y: number` + + The y-coordinate where the click occurred. + + - `keys: optional array of string` + + The keys being held while clicking. + + - `DoubleClick object { keys, type, x, y }` + + A double click action. + + - `keys: array of string` + + The keys being held while double-clicking. + + - `type: "double_click"` + + Specifies the event type. For a double click action, this property is always set to `double_click`. + + - `"double_click"` + + - `x: number` + + The x-coordinate where the double click occurred. + + - `y: number` + + The y-coordinate where the double click occurred. + + - `Drag object { path, type, keys }` + + A drag action. + + - `path: array of object { x, y }` + + An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg + + ``` + [ + { x: 100, y: 200 }, + { x: 200, y: 300 } + ] + ``` + + - `x: number` + + The x-coordinate. + + - `y: number` + + The y-coordinate. + + - `type: "drag"` + + Specifies the event type. For a drag action, this property is always set to `drag`. + + - `"drag"` + + - `keys: optional array of string` + + The keys being held while dragging the mouse. + + - `Keypress object { keys, type }` + + A collection of keypresses the model would like to perform. + + - `keys: array of string` + + The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. + + - `type: "keypress"` + + Specifies the event type. For a keypress action, this property is always set to `keypress`. + + - `"keypress"` + + - `Move object { type, x, y, keys }` + + A mouse move action. + + - `type: "move"` + + Specifies the event type. For a move action, this property is always set to `move`. + + - `"move"` + + - `x: number` + + The x-coordinate to move to. + + - `y: number` + + The y-coordinate to move to. + + - `keys: optional array of string` + + The keys being held while moving the mouse. + + - `Screenshot object { type }` + + A screenshot action. + + - `type: "screenshot"` + + Specifies the event type. For a screenshot action, this property is always set to `screenshot`. + + - `"screenshot"` + + - `Scroll object { scroll_x, scroll_y, type, 3 more }` + + A scroll action. + + - `scroll_x: number` + + The horizontal scroll distance. + + - `scroll_y: number` + + The vertical scroll distance. + + - `type: "scroll"` + + Specifies the event type. For a scroll action, this property is always set to `scroll`. + + - `"scroll"` + + - `x: number` + + The x-coordinate where the scroll occurred. + + - `y: number` + + The y-coordinate where the scroll occurred. + + - `keys: optional array of string` + + The keys being held while scrolling. + + - `Type object { text, type }` + + An action to type in text. + + - `text: string` - Details about the pending safety check. + The text to type. - - `status: "in_progress" or "completed" or "incomplete"` + - `type: "type"` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + Specifies the event type. For a type action, this property is always set to `type`. - - `"in_progress"` + - `"type"` - - `"completed"` + - `Wait object { type }` - - `"incomplete"` + A wait action. - - `type: "computer_call"` + - `type: "wait"` - The type of the computer call. Always `computer_call`. + Specifies the event type. For a wait action, this property is always set to `wait`. - - `"computer_call"` + - `"wait"` - - `action: optional ComputerAction` + - `actions: optional ComputerActionList` - A click action. + Flattened batched actions for `computer_use`. Each action includes an + `type` discriminator and action-specific fields. - `Click object { button, type, x, 2 more }` @@ -23433,47 +27550,6 @@ curl -X DELETE https://api.openai.com/v1/conversations/conv_123/items/msg_abc \ - `"wait"` - - `actions: optional ComputerActionList` - - Flattened batched actions for `computer_use`. Each action includes an - `type` discriminator and action-specific fields. - - - `Click object { button, type, x, 2 more }` - - A click action. - - - `DoubleClick object { keys, type, x, y }` - - A double click action. - - - `Drag object { path, type, keys }` - - A drag action. - - - `Keypress object { keys, type }` - - A collection of keypresses the model would like to perform. - - - `Move object { type, x, y, keys }` - - A mouse move action. - - - `Screenshot object { type }` - - A screenshot action. - - - `Scroll object { scroll_x, scroll_y, type, 3 more }` - - A scroll action. - - - `Type object { text, type }` - - An action to type in text. - - - `Wait object { type }` - - A wait action. - - `ComputerCallOutput object { id, call_id, output, 4 more }` - `id: string` @@ -23613,11 +27689,11 @@ curl -X DELETE https://api.openai.com/v1/conversations/conv_123/items/msg_abc \ - `"incomplete"` - - `tools: array of object { name, parameters, strict, 3 more } or object { type, vector_store_ids, filters, 2 more } or object { type } or 12 more` + - `tools: array of object { name, parameters, strict, 5 more } or object { type, vector_store_ids, filters, 2 more } or object { type } or 13 more` The loaded tool definitions returned by tool search. - - `Function object { name, parameters, strict, 3 more }` + - `Function object { name, parameters, strict, 5 more }` Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). @@ -23631,7 +27707,7 @@ curl -X DELETE https://api.openai.com/v1/conversations/conv_123/items/msg_abc \ - `strict: boolean` - Whether to enforce strict parameter validation. Default `true`. + Whether strict parameter validation is enforced for this function tool. - `type: "function"` @@ -23639,6 +27715,14 @@ curl -X DELETE https://api.openai.com/v1/conversations/conv_123/items/msg_abc \ - `"function"` + - `allowed_callers: optional array of "direct" or "programmatic"` + + The tool invocation context(s). + + - `"direct"` + + - `"programmatic"` + - `defer_loading: optional boolean` Whether this function is deferred and loaded via tool search. @@ -23647,6 +27731,10 @@ curl -X DELETE https://api.openai.com/v1/conversations/conv_123/items/msg_abc \ 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). @@ -23817,7 +27905,7 @@ curl -X DELETE https://api.openai.com/v1/conversations/conv_123/items/msg_abc \ - `WebSearch object { type, filters, search_context_size, user_location }` Search the Internet for sources related to the prompt. Learn more about the - [web search tool](/docs/guides/tools-web-search). + [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - `type: "web_search" or "web_search_2025_08_26"` @@ -23874,10 +27962,10 @@ curl -X DELETE https://api.openai.com/v1/conversations/conv_123/items/msg_abc \ - `"approximate"` - - `Mcp object { server_label, type, allowed_tools, 8 more }` + - `Mcp object { server_label, type, allowed_callers, 9 more }` Give the model access to additional tools via remote Model Context Protocol - (MCP) servers. [Learn more about MCP](/docs/guides/tools-remote-mcp). + (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). - `server_label: string` @@ -23889,6 +27977,14 @@ curl -X DELETE https://api.openai.com/v1/conversations/conv_123/items/msg_abc \ - `"mcp"` + - `allowed_callers: optional array of "direct" or "programmatic"` + + The tool invocation context(s). + + - `"direct"` + + - `"programmatic"` + - `allowed_tools: optional array of string or object { read_only, tool_names }` List of allowed tool names or a filter object. @@ -23921,7 +28017,7 @@ curl -X DELETE https://api.openai.com/v1/conversations/conv_123/items/msg_abc \ Identifier for service connectors, like those available in ChatGPT. One of `server_url`, `connector_id`, or `tunnel_id` must be provided. Learn more - about service connectors [here](/docs/guides/tools-remote-mcp#connectors). + about service connectors [here](https://platform.openai.com/docs/guides/tools-remote-mcp#connectors). Currently supported `connector_id` values are: @@ -24021,7 +28117,7 @@ curl -X DELETE https://api.openai.com/v1/conversations/conv_123/items/msg_abc \ The Secure MCP Tunnel ID to use instead of a direct server URL. One of `server_url`, `connector_id`, or `tunnel_id` must be provided. - - `CodeInterpreter object { container, type }` + - `CodeInterpreter object { container, type, allowed_callers }` A tool that runs Python code to help generate a response to a prompt. @@ -24107,6 +28203,22 @@ curl -X DELETE https://api.openai.com/v1/conversations/conv_123/items/msg_abc \ - `"code_interpreter"` + - `allowed_callers: optional array of "direct" or "programmatic"` + + The tool invocation context(s). + + - `"direct"` + + - `"programmatic"` + + - `ProgrammaticToolCalling object { type }` + + - `type: "programmatic_tool_calling"` + + The type of the tool. Always `programmatic_tool_calling`. + + - `"programmatic_tool_calling"` + - `ImageGeneration object { type, action, background, 9 more }` A tool that generates images using the GPT image models. @@ -24129,8 +28241,19 @@ curl -X DELETE https://api.openai.com/v1/conversations/conv_123/items/msg_abc \ - `background: optional "transparent" or "opaque" or "auto"` - Background type for the generated image. One of `transparent`, - `opaque`, or `auto`. Default: `auto`. + Allows to set transparency for the background of the generated image(s). + This parameter is only supported for GPT image models that support + transparent backgrounds. Must be one of `transparent`, `opaque`, or + `auto` (default value). When `auto` is used, the model will + automatically determine the best background for the image. + + `gpt-image-2` and `gpt-image-2-2026-04-21` do not support + transparent backgrounds. Requests with `background` set to + `transparent` will return an error for these models; use `opaque` or + `auto` instead. + + If `transparent`, the output format needs to support transparency, + so it should be set to either `png` (default value) or `webp`. - `"transparent"` @@ -24159,13 +28282,13 @@ curl -X DELETE https://api.openai.com/v1/conversations/conv_123/items/msg_abc \ Base64-encoded mask image. - - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` + - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-2" or 3 more` The image generation model to use. Default: `gpt-image-1`. - `string` - - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` + - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-2" or 3 more` The image generation model to use. Default: `gpt-image-1`. @@ -24173,8 +28296,14 @@ curl -X DELETE https://api.openai.com/v1/conversations/conv_123/items/msg_abc \ - `"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`. @@ -24243,7 +28372,7 @@ curl -X DELETE https://api.openai.com/v1/conversations/conv_123/items/msg_abc \ - `"local_shell"` - - `Shell object { type, environment }` + - `Shell object { type, allowed_callers, environment }` A tool that allows the model to execute shell commands. @@ -24253,6 +28382,14 @@ curl -X DELETE https://api.openai.com/v1/conversations/conv_123/items/msg_abc \ - `"shell"` + - `allowed_callers: optional array of "direct" or "programmatic"` + + The tool invocation context(s). + + - `"direct"` + + - `"programmatic"` + - `environment: optional ContainerAuto or LocalEnvironment or ContainerReference` - `ContainerAuto object { type, file_ids, memory_limit, 2 more }` @@ -24379,9 +28516,9 @@ curl -X DELETE https://api.openai.com/v1/conversations/conv_123/items/msg_abc \ - `"container_reference"` - - `Custom object { name, type, defer_loading, 2 more }` + - `Custom object { name, type, allowed_callers, 3 more }` - A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) - `name: string` @@ -24393,6 +28530,14 @@ curl -X DELETE https://api.openai.com/v1/conversations/conv_123/items/msg_abc \ - `"custom"` + - `allowed_callers: optional array of "direct" or "programmatic"` + + The tool invocation context(s). + + - `"direct"` + + - `"programmatic"` + - `defer_loading: optional boolean` Whether this tool should be deferred and discovered via tool search. @@ -24449,11 +28594,11 @@ curl -X DELETE https://api.openai.com/v1/conversations/conv_123/items/msg_abc \ The namespace name used in tool calls (for example, `crm`). - - `tools: array of object { name, type, defer_loading, 3 more } or object { name, type, defer_loading, 2 more }` + - `tools: array of object { name, type, allowed_callers, 5 more } or object { name, type, allowed_callers, 3 more }` The function/custom tools available inside this namespace. - - `Function object { name, type, defer_loading, 3 more }` + - `Function object { name, type, allowed_callers, 5 more }` - `name: string` @@ -24461,19 +28606,33 @@ curl -X DELETE https://api.openai.com/v1/conversations/conv_123/items/msg_abc \ - `"function"` + - `allowed_callers: optional array of "direct" or "programmatic"` + + The tool invocation context(s). + + - `"direct"` + + - `"programmatic"` + - `defer_loading: optional boolean` Whether this function should be deferred and discovered via tool search. - `description: optional string` + - `output_schema: optional map[unknown]` + + A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. + - `parameters: optional unknown` - `strict: optional boolean` - - `Custom object { name, type, defer_loading, 2 more }` + Whether to enforce strict parameter validation. If omitted, Responses attempts to use strict validation when the schema is compatible, and falls back to non-strict validation otherwise. + + - `Custom object { name, type, allowed_callers, 3 more }` - A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) - `name: string` @@ -24485,6 +28644,14 @@ curl -X DELETE https://api.openai.com/v1/conversations/conv_123/items/msg_abc \ - `"custom"` + - `allowed_callers: optional array of "direct" or "programmatic"` + + The tool invocation context(s). + + - `"direct"` + + - `"programmatic"` + - `defer_loading: optional boolean` Whether this tool should be deferred and discovered via tool search. @@ -24583,7 +28750,7 @@ curl -X DELETE https://api.openai.com/v1/conversations/conv_123/items/msg_abc \ The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - - `ApplyPatch object { type }` + - `ApplyPatch object { type, allowed_callers }` Allows the assistant to create, delete, or update files using unified diffs. @@ -24593,6 +28760,14 @@ curl -X DELETE https://api.openai.com/v1/conversations/conv_123/items/msg_abc \ - `"apply_patch"` + - `allowed_callers: optional array of "direct" or "programmatic"` + + The tool invocation context(s). + + - `"direct"` + + - `"programmatic"` + - `type: "tool_search_output"` The type of the item. Always `tool_search_output`. @@ -24629,11 +28804,11 @@ curl -X DELETE https://api.openai.com/v1/conversations/conv_123/items/msg_abc \ - `"tool"` - - `tools: array of object { name, parameters, strict, 3 more } or object { type, vector_store_ids, filters, 2 more } or object { type } or 12 more` + - `tools: array of object { name, parameters, strict, 5 more } or object { type, vector_store_ids, filters, 2 more } or object { type } or 13 more` The additional tool definitions made available at this item. - - `Function object { name, parameters, strict, 3 more }` + - `Function object { name, parameters, strict, 5 more }` Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). @@ -24647,7 +28822,7 @@ curl -X DELETE https://api.openai.com/v1/conversations/conv_123/items/msg_abc \ - `strict: boolean` - Whether to enforce strict parameter validation. Default `true`. + Whether strict parameter validation is enforced for this function tool. - `type: "function"` @@ -24655,6 +28830,14 @@ curl -X DELETE https://api.openai.com/v1/conversations/conv_123/items/msg_abc \ - `"function"` + - `allowed_callers: optional array of "direct" or "programmatic"` + + The tool invocation context(s). + + - `"direct"` + + - `"programmatic"` + - `defer_loading: optional boolean` Whether this function is deferred and loaded via tool search. @@ -24663,6 +28846,10 @@ curl -X DELETE https://api.openai.com/v1/conversations/conv_123/items/msg_abc \ 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). @@ -24766,7 +28953,7 @@ curl -X DELETE https://api.openai.com/v1/conversations/conv_123/items/msg_abc \ - `WebSearch object { type, filters, search_context_size, user_location }` Search the Internet for sources related to the prompt. Learn more about the - [web search tool](/docs/guides/tools-web-search). + [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - `type: "web_search" or "web_search_2025_08_26"` @@ -24823,10 +29010,10 @@ curl -X DELETE https://api.openai.com/v1/conversations/conv_123/items/msg_abc \ - `"approximate"` - - `Mcp object { server_label, type, allowed_tools, 8 more }` + - `Mcp object { server_label, type, allowed_callers, 9 more }` Give the model access to additional tools via remote Model Context Protocol - (MCP) servers. [Learn more about MCP](/docs/guides/tools-remote-mcp). + (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). - `server_label: string` @@ -24838,6 +29025,14 @@ curl -X DELETE https://api.openai.com/v1/conversations/conv_123/items/msg_abc \ - `"mcp"` + - `allowed_callers: optional array of "direct" or "programmatic"` + + The tool invocation context(s). + + - `"direct"` + + - `"programmatic"` + - `allowed_tools: optional array of string or object { read_only, tool_names }` List of allowed tool names or a filter object. @@ -24870,7 +29065,7 @@ curl -X DELETE https://api.openai.com/v1/conversations/conv_123/items/msg_abc \ Identifier for service connectors, like those available in ChatGPT. One of `server_url`, `connector_id`, or `tunnel_id` must be provided. Learn more - about service connectors [here](/docs/guides/tools-remote-mcp#connectors). + about service connectors [here](https://platform.openai.com/docs/guides/tools-remote-mcp#connectors). Currently supported `connector_id` values are: @@ -24970,7 +29165,7 @@ curl -X DELETE https://api.openai.com/v1/conversations/conv_123/items/msg_abc \ The Secure MCP Tunnel ID to use instead of a direct server URL. One of `server_url`, `connector_id`, or `tunnel_id` must be provided. - - `CodeInterpreter object { container, type }` + - `CodeInterpreter object { container, type, allowed_callers }` A tool that runs Python code to help generate a response to a prompt. @@ -25024,6 +29219,22 @@ curl -X DELETE https://api.openai.com/v1/conversations/conv_123/items/msg_abc \ - `"code_interpreter"` + - `allowed_callers: optional array of "direct" or "programmatic"` + + The tool invocation context(s). + + - `"direct"` + + - `"programmatic"` + + - `ProgrammaticToolCalling object { type }` + + - `type: "programmatic_tool_calling"` + + The type of the tool. Always `programmatic_tool_calling`. + + - `"programmatic_tool_calling"` + - `ImageGeneration object { type, action, background, 9 more }` A tool that generates images using the GPT image models. @@ -25046,8 +29257,19 @@ curl -X DELETE https://api.openai.com/v1/conversations/conv_123/items/msg_abc \ - `background: optional "transparent" or "opaque" or "auto"` - Background type for the generated image. One of `transparent`, - `opaque`, or `auto`. Default: `auto`. + Allows to set transparency for the background of the generated image(s). + This parameter is only supported for GPT image models that support + transparent backgrounds. Must be one of `transparent`, `opaque`, or + `auto` (default value). When `auto` is used, the model will + automatically determine the best background for the image. + + `gpt-image-2` and `gpt-image-2-2026-04-21` do not support + transparent backgrounds. Requests with `background` set to + `transparent` will return an error for these models; use `opaque` or + `auto` instead. + + If `transparent`, the output format needs to support transparency, + so it should be set to either `png` (default value) or `webp`. - `"transparent"` @@ -25076,13 +29298,13 @@ curl -X DELETE https://api.openai.com/v1/conversations/conv_123/items/msg_abc \ Base64-encoded mask image. - - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` + - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-2" or 3 more` The image generation model to use. Default: `gpt-image-1`. - `string` - - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` + - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-2" or 3 more` The image generation model to use. Default: `gpt-image-1`. @@ -25090,8 +29312,14 @@ curl -X DELETE https://api.openai.com/v1/conversations/conv_123/items/msg_abc \ - `"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`. @@ -25160,7 +29388,7 @@ curl -X DELETE https://api.openai.com/v1/conversations/conv_123/items/msg_abc \ - `"local_shell"` - - `Shell object { type, environment }` + - `Shell object { type, allowed_callers, environment }` A tool that allows the model to execute shell commands. @@ -25170,6 +29398,14 @@ curl -X DELETE https://api.openai.com/v1/conversations/conv_123/items/msg_abc \ - `"shell"` + - `allowed_callers: optional array of "direct" or "programmatic"` + + The tool invocation context(s). + + - `"direct"` + + - `"programmatic"` + - `environment: optional ContainerAuto or LocalEnvironment or ContainerReference` - `ContainerAuto object { type, file_ids, memory_limit, 2 more }` @@ -25178,9 +29414,9 @@ curl -X DELETE https://api.openai.com/v1/conversations/conv_123/items/msg_abc \ - `ContainerReference object { container_id, type }` - - `Custom object { name, type, defer_loading, 2 more }` + - `Custom object { name, type, allowed_callers, 3 more }` - A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) - `name: string` @@ -25192,6 +29428,14 @@ curl -X DELETE https://api.openai.com/v1/conversations/conv_123/items/msg_abc \ - `"custom"` + - `allowed_callers: optional array of "direct" or "programmatic"` + + The tool invocation context(s). + + - `"direct"` + + - `"programmatic"` + - `defer_loading: optional boolean` Whether this tool should be deferred and discovered via tool search. @@ -25216,11 +29460,11 @@ curl -X DELETE https://api.openai.com/v1/conversations/conv_123/items/msg_abc \ The namespace name used in tool calls (for example, `crm`). - - `tools: array of object { name, type, defer_loading, 3 more } or object { name, type, defer_loading, 2 more }` + - `tools: array of object { name, type, allowed_callers, 5 more } or object { name, type, allowed_callers, 3 more }` The function/custom tools available inside this namespace. - - `Function object { name, type, defer_loading, 3 more }` + - `Function object { name, type, allowed_callers, 5 more }` - `name: string` @@ -25228,19 +29472,33 @@ curl -X DELETE https://api.openai.com/v1/conversations/conv_123/items/msg_abc \ - `"function"` + - `allowed_callers: optional array of "direct" or "programmatic"` + + The tool invocation context(s). + + - `"direct"` + + - `"programmatic"` + - `defer_loading: optional boolean` Whether this function should be deferred and discovered via tool search. - `description: optional string` + - `output_schema: optional map[unknown]` + + A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. + - `parameters: optional unknown` - `strict: optional boolean` - - `Custom object { name, type, defer_loading, 2 more }` + Whether to enforce strict parameter validation. If omitted, Responses attempts to use strict validation when the schema is compatible, and falls back to non-strict validation otherwise. + + - `Custom object { name, type, allowed_callers, 3 more }` - A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) + A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) - `name: string` @@ -25252,6 +29510,14 @@ curl -X DELETE https://api.openai.com/v1/conversations/conv_123/items/msg_abc \ - `"custom"` + - `allowed_callers: optional array of "direct" or "programmatic"` + + The tool invocation context(s). + + - `"direct"` + + - `"programmatic"` + - `defer_loading: optional boolean` Whether this tool should be deferred and discovered via tool search. @@ -25350,7 +29616,7 @@ curl -X DELETE https://api.openai.com/v1/conversations/conv_123/items/msg_abc \ The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - - `ApplyPatch object { type }` + - `ApplyPatch object { type, allowed_callers }` Allows the assistant to create, delete, or update files using unified diffs. @@ -25360,6 +29626,14 @@ curl -X DELETE https://api.openai.com/v1/conversations/conv_123/items/msg_abc \ - `"apply_patch"` + - `allowed_callers: optional array of "direct" or "programmatic"` + + The tool invocation context(s). + + - `"direct"` + + - `"programmatic"` + - `type: "additional_tools"` The type of the item. Always `additional_tools`. @@ -25371,13 +29645,13 @@ curl -X DELETE https://api.openai.com/v1/conversations/conv_123/items/msg_abc \ A description of the chain of thought used by a reasoning model while generating a response. Be sure to include these items in your `input` to the Responses API for subsequent turns of a conversation if you are manually - [managing context](/docs/guides/conversation-state). + [managing context](https://platform.openai.com/docs/guides/conversation-state). - `id: string` The unique identifier of the reasoning content. - - `summary: array of SummaryTextContent` + - `summary: array of object { text, type }` Reasoning summary content. @@ -25389,6 +29663,8 @@ curl -X DELETE https://api.openai.com/v1/conversations/conv_123/items/msg_abc \ The type of the object. Always `summary_text`. + - `"summary_text"` + - `type: "reasoning"` The type of the object. Always `reasoning`. @@ -25425,9 +29701,61 @@ curl -X DELETE https://api.openai.com/v1/conversations/conv_123/items/msg_abc \ - `"incomplete"` + - `Program object { id, call_id, code, 2 more }` + + - `id: string` + + The unique ID of the program item. + + - `call_id: string` + + The stable call ID of the program item. + + - `code: string` + + The JavaScript source executed by programmatic tool calling. + + - `fingerprint: string` + + Opaque program replay fingerprint that must be round-tripped. + + - `type: "program"` + + The type of the item. Always `program`. + + - `"program"` + + - `ProgramOutput object { id, call_id, result, 2 more }` + + - `id: string` + + The unique ID of the program output item. + + - `call_id: string` + + The call ID of the program item. + + - `result: string` + + The result produced by the program item. + + - `status: "completed" or "incomplete"` + + The terminal status of the program output item. + + - `"completed"` + + - `"incomplete"` + + - `type: "program_output"` + + The type of the item. Always `program_output`. + + - `"program_output"` + - `Compaction object { id, encrypted_content, type, created_by }` - A compaction item generated by the [`v1/responses/compact` API](/docs/api-reference/responses/compact). + A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact). - `id: string` @@ -25602,7 +29930,7 @@ curl -X DELETE https://api.openai.com/v1/conversations/conv_123/items/msg_abc \ - `"incomplete"` - - `ShellCall object { id, action, call_id, 4 more }` + - `ShellCall object { id, action, call_id, 5 more }` A tool call that executes one or more shell commands in a managed environment. @@ -25670,11 +29998,31 @@ curl -X DELETE https://api.openai.com/v1/conversations/conv_123/items/msg_abc \ - `"shell_call"` + - `caller: optional object { type } or object { caller_id, type }` + + The execution context that produced this tool call. + + - `Direct object { type }` + + - `type: "direct"` + + - `"direct"` + + - `Program object { caller_id, type }` + + - `caller_id: string` + + The call ID of the program item that produced this tool call. + + - `type: "program"` + + - `"program"` + - `created_by: optional string` The ID of the entity that created this tool call. - - `ShellCallOutput object { id, call_id, max_output_length, 4 more }` + - `ShellCallOutput object { id, call_id, max_output_length, 5 more }` The output of a shell tool call that was emitted. @@ -25750,11 +30098,31 @@ curl -X DELETE https://api.openai.com/v1/conversations/conv_123/items/msg_abc \ - `"shell_call_output"` + - `caller: optional object { type } or object { caller_id, type }` + + The execution context that produced this tool call. + + - `Direct object { type }` + + - `type: "direct"` + + - `"direct"` + + - `Program object { caller_id, type }` + + - `caller_id: string` + + The call ID of the program item that produced this tool call. + + - `type: "program"` + + - `"program"` + - `created_by: optional string` The identifier of the actor that created the item. - - `ApplyPatchCall object { id, call_id, operation, 3 more }` + - `ApplyPatchCall object { id, call_id, operation, 4 more }` A tool call that applies file diffs by creating, deleting, or updating files. @@ -25834,11 +30202,31 @@ curl -X DELETE https://api.openai.com/v1/conversations/conv_123/items/msg_abc \ - `"apply_patch_call"` + - `caller: optional object { type } or object { caller_id, type }` + + The execution context that produced this tool call. + + - `Direct object { type }` + + - `type: "direct"` + + - `"direct"` + + - `Program object { caller_id, type }` + + - `caller_id: string` + + The call ID of the program item that produced this tool call. + + - `type: "program"` + + - `"program"` + - `created_by: optional string` The ID of the entity that created this tool call. - - `ApplyPatchCallOutput object { id, call_id, status, 3 more }` + - `ApplyPatchCallOutput object { id, call_id, status, 4 more }` The output emitted by an apply patch tool call. @@ -25864,6 +30252,26 @@ curl -X DELETE https://api.openai.com/v1/conversations/conv_123/items/msg_abc \ - `"apply_patch_call_output"` + - `caller: optional object { type } or object { caller_id, type }` + + The execution context that produced this tool call. + + - `Direct object { type }` + + - `type: "direct"` + + - `"direct"` + + - `Program object { caller_id, type }` + + - `caller_id: string` + + The call ID of the program item that produced this tool call. + + - `type: "program"` + + - `"program"` + - `created_by: optional string` The ID of the entity that created this tool call output. @@ -26019,7 +30427,7 @@ curl -X DELETE https://api.openai.com/v1/conversations/conv_123/items/msg_abc \ - `"failed"` - - `CustomToolCall object { call_id, input, name, 3 more }` + - `CustomToolCall object { call_id, input, name, 4 more }` A call to a custom tool created by the model. @@ -26045,11 +30453,31 @@ curl -X DELETE https://api.openai.com/v1/conversations/conv_123/items/msg_abc \ The unique ID of the custom tool call in the OpenAI platform. + - `caller: optional object { type } or object { caller_id, type }` + + The execution context that produced this tool call. + + - `Direct object { type }` + + - `type: "direct"` + + - `"direct"` + + - `Program object { caller_id, type }` + + - `caller_id: string` + + The call ID of the program item that produced this tool call. + + - `type: "program"` + + - `"program"` + - `namespace: optional string` The namespace of the custom tool being called. - - `CustomToolCallOutput object { call_id, output, type, id }` + - `CustomToolCallOutput object { call_id, output, type, 2 more }` The output of a custom tool call from your code, being sent back to the model. @@ -26070,15 +30498,15 @@ curl -X DELETE https://api.openai.com/v1/conversations/conv_123/items/msg_abc \ Text, image, or file output of the custom tool call. - - `ResponseInputText object { text, type }` + - `ResponseInputText object { text, type, prompt_cache_breakpoint }` A text input to the model. - - `ResponseInputImage object { detail, type, file_id, image_url }` + - `ResponseInputImage object { detail, type, file_id, 2 more }` - An image input to the model. Learn about [image inputs](/docs/guides/vision). + An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). - - `ResponseInputFile object { type, detail, file_data, 3 more }` + - `ResponseInputFile object { type, detail, file_data, 4 more }` A file input to the model. @@ -26092,6 +30520,30 @@ curl -X DELETE https://api.openai.com/v1/conversations/conv_123/items/msg_abc \ 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. + + - `Direct object { type }` + + - `type: "direct"` + + The caller type. Always `direct`. + + - `"direct"` + + - `Program object { caller_id, type }` + + - `caller_id: string` + + The call ID of the program item that produced this tool call. + + - `type: "program"` + + The caller type. Always `program`. + + - `"program"` + - `first_id: string` The ID of the first item in the list.