diff --git a/en/resources/conversations/subresources/items/index.md b/en/resources/conversations/subresources/items/index.md index ef39f0b..27dc6f4 100644 --- a/en/resources/conversations/subresources/items/index.md +++ b/en/resources/conversations/subresources/items/index.md @@ -4,7 +4,7 @@ **post** `/conversations/{conversation_id}/items` -Create items in a conversation with the given ID. +Create items ### Path Parameters @@ -15,7 +15,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"` @@ -35,7 +35,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. @@ -61,7 +61,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. @@ -75,9 +75,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 }` - 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"` @@ -105,7 +115,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. @@ -115,9 +135,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"` @@ -139,6 +161,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 @@ -218,7 +250,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. @@ -322,15 +354,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` @@ -338,15 +372,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` - `ResponseOutputRefusal object { refusal, type }` @@ -398,7 +430,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` @@ -466,7 +498,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` @@ -509,7 +541,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. @@ -713,38 +745,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. @@ -811,7 +998,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` @@ -904,10 +1091,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` @@ -931,6 +1118,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. @@ -946,7 +1153,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. @@ -954,7 +1161,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. @@ -962,11 +1169,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. @@ -980,9 +1187,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"` @@ -1010,7 +1227,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. @@ -1020,9 +1247,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"` @@ -1044,6 +1273,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`. @@ -1054,6 +1293,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. @@ -1104,11 +1367,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). @@ -1122,7 +1385,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"` @@ -1130,6 +1393,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. @@ -1138,6 +1409,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). @@ -1308,7 +1583,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"` @@ -1365,10 +1640,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` @@ -1380,6 +1655,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. @@ -1412,7 +1695,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: @@ -1512,7 +1795,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. @@ -1598,6 +1881,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. @@ -1620,8 +1919,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"` @@ -1650,13 +1960,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`. @@ -1664,8 +1974,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`. @@ -1734,7 +2050,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. @@ -1744,9 +2060,17 @@ Create items in a conversation with the given ID. - `"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"` @@ -1870,9 +2194,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` @@ -1884,6 +2208,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. @@ -1940,11 +2272,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` @@ -1952,19 +2284,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` @@ -1976,6 +2322,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. @@ -2074,7 +2428,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. @@ -2084,6 +2438,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`. @@ -2124,11 +2486,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). @@ -2142,7 +2504,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"` @@ -2150,6 +2512,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. @@ -2158,6 +2528,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). @@ -2261,7 +2635,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"` @@ -2318,10 +2692,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` @@ -2333,6 +2707,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. @@ -2365,7 +2747,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: @@ -2465,7 +2847,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. @@ -2519,6 +2901,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. @@ -2541,8 +2939,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"` @@ -2571,13 +2980,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`. @@ -2585,8 +2994,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`. @@ -2655,7 +3070,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. @@ -2665,6 +3080,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 }` @@ -2673,9 +3096,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` @@ -2687,6 +3110,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. @@ -2711,11 +3142,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` @@ -2723,19 +3154,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` @@ -2747,6 +3192,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. @@ -2845,7 +3298,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. @@ -2855,6 +3308,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`. @@ -2870,13 +3331,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. @@ -2928,7 +3389,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` @@ -3129,7 +3590,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. @@ -3163,6 +3624,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. @@ -3181,7 +3666,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. @@ -3239,6 +3724,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. @@ -3253,7 +3762,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. @@ -3333,7 +3842,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. @@ -3359,6 +3892,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). @@ -3510,7 +4067,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. @@ -3531,15 +4088,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. @@ -3553,7 +4110,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. @@ -3579,6 +4160,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. @@ -3607,6 +4208,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 }` @@ -3629,7 +4282,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. @@ -3643,7 +4296,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. @@ -3747,15 +4410,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` @@ -3763,15 +4428,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 }` @@ -3825,9 +4488,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"` @@ -3855,7 +4518,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. @@ -3885,7 +4558,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. @@ -3895,9 +4578,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"` @@ -3919,6 +4604,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`. @@ -3963,7 +4658,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` @@ -3998,6 +4693,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. @@ -4006,7 +4721,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` @@ -4029,15 +4744,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. @@ -4058,6 +4773,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. @@ -4065,7 +4804,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` @@ -4133,7 +4872,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` @@ -4259,7 +4998,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` @@ -4302,7 +5041,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. @@ -4506,38 +5245,193 @@ 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`. + + - `"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 { id, call_id, output, 4 more }` - `id: string` @@ -4677,11 +5571,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). @@ -4695,7 +5589,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"` @@ -4703,6 +5597,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. @@ -4711,6 +5613,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). @@ -4881,7 +5787,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"` @@ -4938,10 +5844,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` @@ -4953,6 +5859,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. @@ -4985,7 +5899,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: @@ -5085,7 +5999,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. @@ -5171,6 +6085,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. @@ -5193,8 +6123,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"` @@ -5223,13 +6164,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`. @@ -5237,8 +6178,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`. @@ -5307,7 +6254,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. @@ -5317,6 +6264,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 }` @@ -5443,9 +6398,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` @@ -5457,6 +6412,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. @@ -5513,11 +6476,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` @@ -5525,19 +6488,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` @@ -5549,6 +6526,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. @@ -5647,7 +6632,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. @@ -5657,6 +6642,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`. @@ -5693,11 +6686,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). @@ -5711,7 +6704,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"` @@ -5719,6 +6712,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. @@ -5727,6 +6728,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). @@ -5830,7 +6835,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"` @@ -5887,10 +6892,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` @@ -5902,6 +6907,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. @@ -5934,7 +6947,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: @@ -6034,7 +7047,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. @@ -6088,6 +7101,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. @@ -6110,8 +7139,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"` @@ -6140,13 +7180,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`. @@ -6154,8 +7194,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`. @@ -6224,7 +7270,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. @@ -6234,6 +7280,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 }` @@ -6242,9 +7296,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` @@ -6256,6 +7310,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. @@ -6280,11 +7342,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` @@ -6292,19 +7354,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` @@ -6316,6 +7392,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. @@ -6414,7 +7498,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. @@ -6424,6 +7508,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`. @@ -6435,13 +7527,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. @@ -6453,6 +7545,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`. @@ -6489,17 +7583,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"` @@ -6666,7 +7812,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. @@ -6734,11 +7880,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. @@ -6814,11 +7980,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. @@ -6898,11 +8084,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. @@ -6928,6 +8134,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. @@ -7083,7 +8309,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. @@ -7109,11 +8335,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. @@ -7134,15 +8380,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. @@ -7156,6 +8402,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. @@ -7201,7 +8471,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", @@ -7278,7 +8551,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 @@ -7356,7 +8629,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. @@ -7370,7 +8643,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. @@ -7474,15 +8757,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` @@ -7490,15 +8775,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 }` @@ -7552,9 +8835,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"` @@ -7582,7 +8865,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. @@ -7612,7 +8905,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. @@ -7622,9 +8925,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"` @@ -7646,6 +8951,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`. @@ -7690,7 +9005,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` @@ -7725,6 +9040,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. @@ -7733,7 +9068,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` @@ -7756,15 +9091,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. @@ -7785,6 +9120,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. @@ -7792,7 +9151,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` @@ -7860,7 +9219,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` @@ -7986,7 +9345,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` @@ -8029,7 +9388,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. @@ -8233,92 +9592,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. @@ -8404,11 +9918,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). @@ -8422,7 +9936,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"` @@ -8430,6 +9944,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. @@ -8438,6 +9960,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). @@ -8608,7 +10134,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"` @@ -8665,10 +10191,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` @@ -8680,6 +10206,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. @@ -8712,7 +10246,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: @@ -8812,7 +10346,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. @@ -8898,6 +10432,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. @@ -8920,8 +10470,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"` @@ -8950,13 +10511,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`. @@ -8964,8 +10525,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`. @@ -9034,7 +10601,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. @@ -9044,6 +10611,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 }` @@ -9170,9 +10745,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` @@ -9184,6 +10759,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. @@ -9240,11 +10823,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` @@ -9252,19 +10835,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` @@ -9276,6 +10873,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. @@ -9374,7 +10979,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. @@ -9384,6 +10989,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`. @@ -9420,11 +11033,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). @@ -9438,7 +11051,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"` @@ -9446,6 +11059,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. @@ -9454,6 +11075,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). @@ -9557,7 +11182,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"` @@ -9614,10 +11239,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` @@ -9629,6 +11254,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. @@ -9661,7 +11294,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: @@ -9761,7 +11394,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. @@ -9815,6 +11448,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. @@ -9837,8 +11486,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"` @@ -9867,13 +11527,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`. @@ -9881,8 +11541,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`. @@ -9951,7 +11617,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. @@ -9961,6 +11627,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 }` @@ -9969,9 +11643,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` @@ -9983,6 +11657,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. @@ -10007,11 +11689,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` @@ -10019,19 +11701,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` @@ -10043,6 +11739,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. @@ -10141,7 +11845,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. @@ -10151,6 +11855,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`. @@ -10162,13 +11874,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. @@ -10180,6 +11892,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`. @@ -10216,19 +11930,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`. @@ -10393,7 +12159,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. @@ -10461,11 +12227,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. @@ -10541,11 +12327,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. @@ -10625,11 +12431,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. @@ -10655,6 +12481,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. @@ -10810,7 +12656,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. @@ -10836,11 +12682,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. @@ -10861,15 +12727,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. @@ -10883,6 +12749,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. @@ -10918,7 +12808,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", @@ -10967,7 +12860,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 @@ -10980,7 +12873,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"` @@ -11000,9 +12893,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 }` @@ -11016,7 +12909,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. @@ -11030,7 +12923,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. @@ -11134,15 +13037,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` @@ -11150,15 +13055,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 }` @@ -11212,9 +13115,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"` @@ -11242,7 +13145,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. @@ -11272,7 +13185,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. @@ -11282,9 +13205,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"` @@ -11306,6 +13231,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`. @@ -11350,7 +13285,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` @@ -11385,6 +13320,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. @@ -11393,7 +13348,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` @@ -11416,15 +13371,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. @@ -11445,6 +13400,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. @@ -11452,7 +13431,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` @@ -11520,7 +13499,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` @@ -11646,7 +13625,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` @@ -11689,7 +13668,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. @@ -11893,92 +13872,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. @@ -12064,11 +14198,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). @@ -12082,7 +14216,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"` @@ -12090,6 +14224,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. @@ -12098,6 +14240,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). @@ -12268,7 +14414,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"` @@ -12325,10 +14471,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` @@ -12340,6 +14486,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. @@ -12372,7 +14526,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: @@ -12472,7 +14626,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. @@ -12558,6 +14712,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. @@ -12580,8 +14750,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"` @@ -12610,13 +14791,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`. @@ -12624,8 +14805,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`. @@ -12694,7 +14881,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. @@ -12704,6 +14891,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 }` @@ -12830,9 +15025,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` @@ -12844,6 +15039,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. @@ -12900,11 +15103,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` @@ -12912,19 +15115,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` @@ -12936,6 +15153,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. @@ -13034,7 +15259,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. @@ -13044,6 +15269,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`. @@ -13080,11 +15313,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). @@ -13098,7 +15331,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"` @@ -13106,6 +15339,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. @@ -13114,6 +15355,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). @@ -13217,7 +15462,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"` @@ -13274,10 +15519,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` @@ -13289,6 +15534,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. @@ -13321,7 +15574,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: @@ -13421,7 +15674,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. @@ -13475,6 +15728,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. @@ -13497,8 +15766,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"` @@ -13527,13 +15807,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`. @@ -13541,8 +15821,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`. @@ -13611,7 +15897,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. @@ -13621,6 +15907,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 }` @@ -13629,9 +15923,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` @@ -13643,6 +15937,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. @@ -13667,11 +15969,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` @@ -13679,19 +15981,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` @@ -13703,6 +16019,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. @@ -13801,7 +16125,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. @@ -13811,6 +16135,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`. @@ -13822,13 +16154,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. @@ -13840,6 +16172,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`. @@ -13876,19 +16210,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`. @@ -14053,7 +16439,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. @@ -14121,11 +16507,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. @@ -14201,11 +16607,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. @@ -14285,11 +16711,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. @@ -14315,6 +16761,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. @@ -14470,7 +16936,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. @@ -14496,11 +16962,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. @@ -14521,15 +17007,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. @@ -14543,6 +17029,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 @@ -14558,7 +17068,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", @@ -14593,7 +17106,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 @@ -14665,9 +17178,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 }` @@ -14681,7 +17194,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. @@ -14695,7 +17208,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. @@ -14799,15 +17322,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` @@ -14815,15 +17340,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 }` @@ -14877,9 +17400,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"` @@ -14907,7 +17430,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. @@ -14937,7 +17470,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. @@ -14947,9 +17490,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"` @@ -14971,6 +17516,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`. @@ -15015,7 +17570,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` @@ -15050,6 +17605,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. @@ -15058,7 +17633,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` @@ -15081,15 +17656,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. @@ -15110,6 +17685,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. @@ -15117,7 +17716,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` @@ -15185,7 +17784,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` @@ -15311,7 +17910,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` @@ -15354,7 +17953,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. @@ -15558,92 +18157,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. @@ -15729,11 +18483,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). @@ -15747,7 +18501,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"` @@ -15755,6 +18509,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. @@ -15763,6 +18525,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). @@ -15933,7 +18699,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"` @@ -15990,10 +18756,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` @@ -16005,6 +18771,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. @@ -16037,7 +18811,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: @@ -16137,7 +18911,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. @@ -16223,6 +18997,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. @@ -16245,8 +19035,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"` @@ -16275,13 +19076,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`. @@ -16289,8 +19090,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`. @@ -16359,7 +19166,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. @@ -16369,6 +19176,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 }` @@ -16495,9 +19310,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` @@ -16509,6 +19324,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. @@ -16565,11 +19388,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` @@ -16577,19 +19400,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` @@ -16601,6 +19438,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. @@ -16699,7 +19544,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. @@ -16709,6 +19554,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`. @@ -16745,11 +19598,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). @@ -16763,7 +19616,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"` @@ -16771,6 +19624,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. @@ -16779,6 +19640,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). @@ -16882,7 +19747,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"` @@ -16939,10 +19804,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` @@ -16954,6 +19819,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. @@ -16986,7 +19859,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: @@ -17086,7 +19959,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. @@ -17140,6 +20013,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. @@ -17162,8 +20051,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"` @@ -17192,13 +20092,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`. @@ -17206,8 +20106,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`. @@ -17276,7 +20182,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. @@ -17286,6 +20192,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 }` @@ -17294,9 +20208,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` @@ -17308,6 +20222,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. @@ -17332,11 +20254,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` @@ -17344,19 +20266,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` @@ -17368,6 +20304,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. @@ -17466,7 +20410,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. @@ -17476,6 +20420,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`. @@ -17487,13 +20439,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. @@ -17505,6 +20457,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`. @@ -17541,19 +20495,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`. @@ -17718,7 +20724,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. @@ -17786,11 +20792,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. @@ -17866,11 +20892,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. @@ -17950,11 +20996,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. @@ -17980,6 +21046,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. @@ -18135,7 +21221,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. @@ -18161,11 +21247,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. @@ -18186,15 +21292,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. @@ -18208,6 +21314,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 }` @@ -18230,7 +21360,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. @@ -18244,7 +21374,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. @@ -18348,15 +21488,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` @@ -18364,15 +21506,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 }` @@ -18426,9 +21566,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"` @@ -18456,7 +21596,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. @@ -18486,7 +21636,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. @@ -18496,9 +21656,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"` @@ -18520,6 +21682,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`. @@ -18564,7 +21736,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` @@ -18599,6 +21771,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. @@ -18607,7 +21799,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` @@ -18630,15 +21822,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. @@ -18659,6 +21851,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. @@ -18666,7 +21882,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` @@ -18734,7 +21950,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` @@ -18860,7 +22076,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` @@ -18882,30 +22098,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 }` @@ -19098,47 +22510,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` @@ -19278,11 +22649,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). @@ -19296,7 +22667,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"` @@ -19304,6 +22675,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. @@ -19312,6 +22691,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). @@ -19482,7 +22865,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"` @@ -19539,10 +22922,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` @@ -19554,6 +22937,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. @@ -19586,7 +22977,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: @@ -19686,7 +23077,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. @@ -19772,6 +23163,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. @@ -19794,8 +23201,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"` @@ -19824,13 +23242,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`. @@ -19838,8 +23256,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`. @@ -19908,7 +23332,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. @@ -19918,6 +23342,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 }` @@ -20044,9 +23476,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` @@ -20058,6 +23490,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. @@ -20114,11 +23554,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` @@ -20126,19 +23566,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` @@ -20150,6 +23604,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. @@ -20248,7 +23710,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. @@ -20258,6 +23720,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`. @@ -20294,11 +23764,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). @@ -20312,7 +23782,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"` @@ -20320,6 +23790,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. @@ -20328,6 +23806,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). @@ -20431,7 +23913,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"` @@ -20488,10 +23970,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` @@ -20503,6 +23985,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. @@ -20535,7 +24025,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: @@ -20635,7 +24125,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. @@ -20689,6 +24179,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. @@ -20711,8 +24217,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"` @@ -20741,13 +24258,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`. @@ -20755,8 +24272,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`. @@ -20825,7 +24348,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. @@ -20835,6 +24358,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 }` @@ -20843,9 +24374,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` @@ -20857,6 +24388,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. @@ -20881,11 +24420,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` @@ -20893,19 +24432,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` @@ -20917,6 +24470,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. @@ -21015,7 +24576,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. @@ -21025,6 +24586,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`. @@ -21036,13 +24605,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. @@ -21054,6 +24623,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`. @@ -21090,9 +24661,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` @@ -21267,7 +24890,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. @@ -21335,11 +24958,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. @@ -21415,11 +25058,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. @@ -21499,11 +25162,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. @@ -21529,6 +25212,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. @@ -21684,7 +25387,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. @@ -21710,11 +25413,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. @@ -21735,15 +25458,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. @@ -21757,6 +25480,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.