diff --git a/en/resources/conversations/index.md b/en/resources/conversations/index.md index b576493..3f5c633 100644 --- a/en/resources/conversations/index.md +++ b/en/resources/conversations/index.md @@ -8,7 +8,7 @@ Create a conversation. ### Body Parameters -- `items: optional array of EasyInputMessage or object { content, role, status, type } or ResponseOutputMessage or 26 more` +- `items: optional array of EasyInputMessage or object { content, role, status, type } or ResponseOutputMessage or 27 more` Initial items to include in the conversation context. You may add up to 20 items at a time. @@ -790,19 +790,15 @@ Create a conversation. The unique ID of the web search tool call. - - `action: object { query, type, queries, sources } or object { type, url } or object { pattern, type, url }` + - `action: object { type, queries, query, sources } or object { type, url } or object { pattern, type, url }` An object describing the specific action taken in this web search call. Includes details on how the model used the web (search, open_page, find_in_page). - - `Search object { query, type, queries, sources }` + - `Search object { type, queries, query, sources }` Action type "search" - Performs a web search query. - - `query: string` - - [DEPRECATED] The search query. - - `type: "search"` The action type. @@ -813,6 +809,10 @@ Create a conversation. The search queries. + - `query: optional string` + + The search query. + - `sources: optional array of object { type, url }` The sources used in the search. @@ -2084,2610 +2084,7928 @@ Create a conversation. - `"incomplete"` - - `Reasoning object { id, summary, type, 3 more }` - - 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). + - `AdditionalTools object { role, tools, type, id }` - - `id: string` + - `role: "developer"` - The unique identifier of the reasoning content. + The role that provided the additional tools. Only `developer` is supported. - - `summary: array of SummaryTextContent` + - `"developer"` - Reasoning summary content. + - `tools: array of object { name, parameters, strict, 3 more } or object { type, vector_store_ids, filters, 2 more } or object { type } or 12 more` - - `text: string` + A list of additional tools made available at this item. - A summary of the reasoning output from the model so far. + - `Function object { name, parameters, strict, 3 more }` - - `type: "summary_text"` + Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). - The type of the object. Always `summary_text`. + - `name: string` - - `"summary_text"` + The name of the function to call. - - `type: "reasoning"` + - `parameters: map[unknown]` - The type of the object. Always `reasoning`. + A JSON schema object describing the parameters of the function. - - `"reasoning"` + - `strict: boolean` - - `content: optional array of object { text, type }` + Whether to enforce strict parameter validation. Default `true`. - Reasoning text content. + - `type: "function"` - - `text: string` + The type of the function tool. Always `function`. - The reasoning text from the model. + - `"function"` - - `type: "reasoning_text"` + - `defer_loading: optional boolean` - The type of the reasoning text. Always `reasoning_text`. + Whether this function is deferred and loaded via tool search. - - `"reasoning_text"` + - `description: optional string` - - `encrypted_content: optional string` + A description of the function. Used by the model to determine whether or not to call the function. - The encrypted content of the reasoning item - populated when a response is - generated with `reasoning.encrypted_content` in the `include` parameter. + - `FileSearch object { type, vector_store_ids, filters, 2 more }` - - `status: optional "in_progress" or "completed" or "incomplete"` + A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `type: "file_search"` - - `"in_progress"` + The type of the file search tool. Always `file_search`. - - `"completed"` + - `"file_search"` - - `"incomplete"` + - `vector_store_ids: array of string` - - `Compaction object { encrypted_content, type, id }` + The IDs of the vector stores to search. - A compaction item generated by the [`v1/responses/compact` API](/docs/api-reference/responses/compact). + - `filters: optional ComparisonFilter or CompoundFilter` - - `encrypted_content: string` + A filter to apply. - The encrypted content of the compaction summary. + - `ComparisonFilter object { key, type, value }` - - `type: "compaction"` + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - The type of the item. Always `compaction`. + - `CompoundFilter object { filters, type }` - - `"compaction"` + Combine multiple filters using `and` or `or`. - - `id: optional string` + - `max_num_results: optional number` - The ID of the compaction item. + The maximum number of results to return. This number should be between 1 and 50 inclusive. - - `ImageGenerationCall object { id, result, status, type }` + - `ranking_options: optional object { hybrid_search, ranker, score_threshold }` - An image generation request made by the model. + Ranking options for search. - - `id: string` + - `hybrid_search: optional object { embedding_weight, text_weight }` - The unique ID of the image generation call. + Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. - - `result: string` + - `embedding_weight: number` - The generated image encoded in base64. + The weight of the embedding in the reciprocal ranking fusion. - - `status: "in_progress" or "completed" or "generating" or "failed"` + - `text_weight: number` - The status of the image generation call. + The weight of the text in the reciprocal ranking fusion. - - `"in_progress"` + - `ranker: optional "auto" or "default-2024-11-15"` - - `"completed"` + The ranker to use for the file search. - - `"generating"` + - `"auto"` - - `"failed"` + - `"default-2024-11-15"` - - `type: "image_generation_call"` + - `score_threshold: optional number` - The type of the image generation call. Always `image_generation_call`. + The score threshold for the file search, a number between 0 and 1. Numbers closer to 1 will attempt to return only the most relevant results, but may return fewer results. - - `"image_generation_call"` + - `Computer object { type }` - - `CodeInterpreterCall object { id, code, container_id, 3 more }` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - A tool call to run code. + - `type: "computer"` - - `id: string` + The type of the computer tool. Always `computer`. - The unique ID of the code interpreter tool call. + - `"computer"` - - `code: string` + - `ComputerUsePreview object { display_height, display_width, environment, type }` - The code to run, or null if not available. + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `container_id: string` + - `display_height: number` - The ID of the container used to run the code. + The height of the computer display. - - `outputs: array of object { logs, type } or object { type, url }` + - `display_width: number` - The outputs generated by the code interpreter, such as logs or images. - Can be null if no outputs are available. + The width of the computer display. - - `Logs object { logs, type }` + - `environment: "windows" or "mac" or "linux" or 2 more` - The logs output from the code interpreter. + The type of computer environment to control. - - `logs: string` + - `"windows"` - The logs output from the code interpreter. + - `"mac"` - - `type: "logs"` + - `"linux"` - The type of the output. Always `logs`. + - `"ubuntu"` - - `"logs"` + - `"browser"` - - `Image object { type, url }` + - `type: "computer_use_preview"` - The image output from the code interpreter. + The type of the computer use tool. Always `computer_use_preview`. - - `type: "image"` + - `"computer_use_preview"` - The type of the output. Always `image`. + - `WebSearch object { type, filters, search_context_size, user_location }` - - `"image"` + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](/docs/guides/tools-web-search). - - `url: string` + - `type: "web_search" or "web_search_2025_08_26"` - The URL of the image output from the code interpreter. + The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. - - `status: "in_progress" or "completed" or "incomplete" or 2 more` + - `"web_search"` - The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. + - `"web_search_2025_08_26"` - - `"in_progress"` + - `filters: optional object { allowed_domains }` - - `"completed"` + Filters for the search. - - `"incomplete"` + - `allowed_domains: optional array of string` - - `"interpreting"` + Allowed domains for the search. If not provided, all domains are allowed. + Subdomains of the provided domains are allowed as well. - - `"failed"` + Example: `["pubmed.ncbi.nlm.nih.gov"]` - - `type: "code_interpreter_call"` + - `search_context_size: optional "low" or "medium" or "high"` - The type of the code interpreter tool call. Always `code_interpreter_call`. + High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. - - `"code_interpreter_call"` + - `"low"` - - `LocalShellCall object { id, action, call_id, 2 more }` + - `"medium"` - A tool call to run a command on the local shell. + - `"high"` - - `id: string` + - `user_location: optional object { city, country, region, 2 more }` - The unique ID of the local shell call. + The approximate location of the user. - - `action: object { command, env, type, 3 more }` + - `city: optional string` - Execute a shell command on the server. + Free text input for the city of the user, e.g. `San Francisco`. - - `command: array of string` + - `country: optional string` - The command to run. + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - - `env: map[string]` + - `region: optional string` - Environment variables to set for the command. + Free text input for the region of the user, e.g. `California`. - - `type: "exec"` + - `timezone: optional string` - The type of the local shell action. Always `exec`. + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - - `"exec"` + - `type: optional "approximate"` - - `timeout_ms: optional number` + The type of location approximation. Always `approximate`. - Optional timeout in milliseconds for the command. + - `"approximate"` - - `user: optional string` + - `Mcp object { server_label, type, allowed_tools, 7 more }` - Optional user to run the command as. + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](/docs/guides/tools-remote-mcp). - - `working_directory: optional string` + - `server_label: string` - Optional working directory to run the command in. + A label for this MCP server, used to identify it in tool calls. - - `call_id: string` + - `type: "mcp"` - The unique ID of the local shell tool call generated by the model. + The type of the MCP tool. Always `mcp`. - - `status: "in_progress" or "completed" or "incomplete"` + - `"mcp"` - The status of the local shell call. + - `allowed_tools: optional array of string or object { read_only, tool_names }` - - `"in_progress"` + List of allowed tool names or a filter object. - - `"completed"` + - `McpAllowedTools = array of string` - - `"incomplete"` + A string array of allowed tool names - - `type: "local_shell_call"` + - `McpToolFilter object { read_only, tool_names }` - The type of the local shell call. Always `local_shell_call`. + A filter object to specify which tools are allowed. - - `"local_shell_call"` + - `read_only: optional boolean` - - `LocalShellCallOutput object { id, output, type, status }` + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. - The output of a local shell tool call. + - `tool_names: optional array of string` - - `id: string` + List of allowed tool names. - The unique ID of the local shell tool call generated by the model. + - `authorization: optional string` - - `output: string` + An OAuth access token that can be used with a remote MCP server, either + with a custom MCP server URL or a service connector. Your application + must handle the OAuth authorization flow and provide the token here. - A JSON string of the output of the local shell tool call. + - `connector_id: optional "connector_dropbox" or "connector_gmail" or "connector_googlecalendar" or 5 more` - - `type: "local_shell_call_output"` + Identifier for service connectors, like those available in ChatGPT. One of + `server_url` or `connector_id` must be provided. Learn more about service + connectors [here](/docs/guides/tools-remote-mcp#connectors). - The type of the local shell tool call output. Always `local_shell_call_output`. + Currently supported `connector_id` values are: - - `"local_shell_call_output"` + - Dropbox: `connector_dropbox` + - Gmail: `connector_gmail` + - Google Calendar: `connector_googlecalendar` + - Google Drive: `connector_googledrive` + - Microsoft Teams: `connector_microsoftteams` + - Outlook Calendar: `connector_outlookcalendar` + - Outlook Email: `connector_outlookemail` + - SharePoint: `connector_sharepoint` - - `status: optional "in_progress" or "completed" or "incomplete"` + - `"connector_dropbox"` - The status of the item. One of `in_progress`, `completed`, or `incomplete`. + - `"connector_gmail"` - - `"in_progress"` + - `"connector_googlecalendar"` - - `"completed"` + - `"connector_googledrive"` - - `"incomplete"` + - `"connector_microsoftteams"` - - `ShellCall object { action, call_id, type, 3 more }` + - `"connector_outlookcalendar"` - A tool representing a request to execute one or more shell commands. + - `"connector_outlookemail"` - - `action: object { commands, max_output_length, timeout_ms }` + - `"connector_sharepoint"` - The shell commands and limits that describe how to run the tool call. + - `defer_loading: optional boolean` - - `commands: array of string` + Whether this MCP tool is deferred and discovered via tool search. - Ordered shell commands for the execution environment to run. + - `headers: optional map[string]` - - `max_output_length: optional number` + Optional HTTP headers to send to the MCP server. Use for authentication + or other purposes. - Maximum number of UTF-8 characters to capture from combined stdout and stderr output. + - `require_approval: optional object { always, never } or "always" or "never"` - - `timeout_ms: optional number` + Specify which of the MCP server's tools require approval. - Maximum wall-clock time in milliseconds to allow the shell commands to run. + - `McpToolApprovalFilter object { always, never }` - - `call_id: string` + Specify which of the MCP server's tools require approval. Can be + `always`, `never`, or a filter object associated with tools + that require approval. - The unique ID of the shell tool call generated by the model. + - `always: optional object { read_only, tool_names }` - - `type: "shell_call"` + A filter object to specify which tools are allowed. - The type of the item. Always `shell_call`. + - `read_only: optional boolean` - - `"shell_call"` + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. - - `id: optional string` + - `tool_names: optional array of string` - The unique ID of the shell tool call. Populated when this item is returned via API. + List of allowed tool names. - - `environment: optional LocalEnvironment or ContainerReference` + - `never: optional object { read_only, tool_names }` - The environment to execute the shell commands in. + A filter object to specify which tools are allowed. - - `LocalEnvironment object { type, skills }` + - `read_only: optional boolean` - - `ContainerReference object { container_id, type }` + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. - - `status: optional "in_progress" or "completed" or "incomplete"` + - `tool_names: optional array of string` - The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. + List of allowed tool names. - - `"in_progress"` + - `McpToolApprovalSetting = "always" or "never"` - - `"completed"` + Specify a single approval policy for all tools. One of `always` or + `never`. When set to `always`, all tools will require approval. When + set to `never`, all tools will not require approval. - - `"incomplete"` + - `"always"` - - `ShellCallOutput object { call_id, output, type, 3 more }` + - `"never"` - The streamed output items emitted by a shell tool call. + - `server_description: optional string` - - `call_id: string` + Optional description of the MCP server, used to provide more context. - The unique ID of the shell tool call generated by the model. + - `server_url: optional string` - - `output: array of ResponseFunctionShellCallOutputContent` + The URL for the MCP server. One of `server_url` or `connector_id` must be + provided. - Captured chunks of stdout and stderr output, along with their associated outcomes. + - `CodeInterpreter object { container, type }` - - `outcome: object { type } or object { exit_code, type }` + A tool that runs Python code to help generate a response to a prompt. - The exit or timeout outcome associated with this shell call. + - `container: string or object { type, file_ids, memory_limit, network_policy }` - - `Timeout object { type }` + The code interpreter container. Can be a container ID or an object that + specifies uploaded file IDs to make available to your code, along with an + optional `memory_limit` setting. - Indicates that the shell call exceeded its configured time limit. + - `string` - - `type: "timeout"` + The container ID. - The outcome type. Always `timeout`. + - `CodeInterpreterToolAuto object { type, file_ids, memory_limit, network_policy }` - - `"timeout"` + Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. - - `Exit object { exit_code, type }` + - `type: "auto"` - Indicates that the shell commands finished and returned an exit code. + Always `auto`. - - `exit_code: number` + - `"auto"` - The exit code returned by the shell process. + - `file_ids: optional array of string` - - `type: "exit"` + An optional list of uploaded files to make available to your code. - The outcome type. Always `exit`. + - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` - - `"exit"` + The memory limit for the code interpreter container. - - `stderr: string` + - `"1g"` - Captured stderr output for the shell call. + - `"4g"` - - `stdout: string` + - `"16g"` - Captured stdout output for the shell call. + - `"64g"` - - `type: "shell_call_output"` + - `network_policy: optional ContainerNetworkPolicyDisabled or ContainerNetworkPolicyAllowlist` - The type of the item. Always `shell_call_output`. + Network access policy for the container. - - `"shell_call_output"` + - `ContainerNetworkPolicyDisabled object { type }` - - `id: optional string` + - `ContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` - The unique ID of the shell tool call output. Populated when this item is returned via API. + - `type: "code_interpreter"` - - `max_output_length: optional number` + The type of the code interpreter tool. Always `code_interpreter`. - The maximum number of UTF-8 characters captured for this shell call's combined output. + - `"code_interpreter"` - - `status: optional "in_progress" or "completed" or "incomplete"` + - `ImageGeneration object { type, action, background, 9 more }` - The status of the shell call output. + A tool that generates images using the GPT image models. - - `"in_progress"` + - `type: "image_generation"` - - `"completed"` + The type of the image generation tool. Always `image_generation`. - - `"incomplete"` + - `"image_generation"` - - `ApplyPatchCall object { call_id, operation, status, 2 more }` + - `action: optional "generate" or "edit" or "auto"` - A tool call representing a request to create, delete, or update files using diff patches. + Whether to generate a new image or edit an existing image. Default: `auto`. - - `call_id: string` + - `"generate"` - The unique ID of the apply patch tool call generated by the model. + - `"edit"` - - `operation: object { diff, path, type } or object { path, type } or object { diff, path, type }` + - `"auto"` - The specific create, delete, or update instruction for the apply_patch tool call. + - `background: optional "transparent" or "opaque" or "auto"` - - `CreateFile object { diff, path, type }` + Background type for the generated image. One of `transparent`, + `opaque`, or `auto`. Default: `auto`. - Instruction for creating a new file via the apply_patch tool. + - `"transparent"` - - `diff: string` + - `"opaque"` - Unified diff content to apply when creating the file. + - `"auto"` - - `path: string` + - `input_fidelity: optional "high" or "low"` - Path of the file to create relative to the workspace root. + Control how much effort the model will exert to match the style and features, especially facial features, of input images. This parameter is only supported for `gpt-image-1` and `gpt-image-1.5` and later models, unsupported for `gpt-image-1-mini`. Supports `high` and `low`. Defaults to `low`. - - `type: "create_file"` + - `"high"` - The operation type. Always `create_file`. + - `"low"` - - `"create_file"` + - `input_image_mask: optional object { file_id, image_url }` - - `DeleteFile object { path, type }` + Optional mask for inpainting. Contains `image_url` + (string, optional) and `file_id` (string, optional). - Instruction for deleting an existing file via the apply_patch tool. + - `file_id: optional string` - - `path: string` + File ID for the mask image. - Path of the file to delete relative to the workspace root. + - `image_url: optional string` - - `type: "delete_file"` + Base64-encoded mask image. - The operation type. Always `delete_file`. + - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` - - `"delete_file"` + The image generation model to use. Default: `gpt-image-1`. - - `UpdateFile object { diff, path, type }` + - `string` - Instruction for updating an existing file via the apply_patch tool. + - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` - - `diff: string` + The image generation model to use. Default: `gpt-image-1`. - Unified diff content to apply to the existing file. + - `"gpt-image-1"` - - `path: string` + - `"gpt-image-1-mini"` - Path of the file to update relative to the workspace root. + - `"gpt-image-1.5"` - - `type: "update_file"` + - `moderation: optional "auto" or "low"` - The operation type. Always `update_file`. + Moderation level for the generated image. Default: `auto`. - - `"update_file"` + - `"auto"` - - `status: "in_progress" or "completed"` + - `"low"` - The status of the apply patch tool call. One of `in_progress` or `completed`. + - `output_compression: optional number` - - `"in_progress"` + Compression level for the output image. Default: 100. - - `"completed"` + - `output_format: optional "png" or "webp" or "jpeg"` - - `type: "apply_patch_call"` + The output format of the generated image. One of `png`, `webp`, or + `jpeg`. Default: `png`. - The type of the item. Always `apply_patch_call`. + - `"png"` - - `"apply_patch_call"` + - `"webp"` - - `id: optional string` + - `"jpeg"` - The unique ID of the apply patch tool call. Populated when this item is returned via API. + - `partial_images: optional number` - - `ApplyPatchCallOutput object { call_id, status, type, 2 more }` + Number of partial images to generate in streaming mode, from 0 (default value) to 3. - The streamed output emitted by an apply patch tool call. + - `quality: optional "low" or "medium" or "high" or "auto"` - - `call_id: string` + The quality of the generated image. One of `low`, `medium`, `high`, + or `auto`. Default: `auto`. - The unique ID of the apply patch tool call generated by the model. + - `"low"` - - `status: "completed" or "failed"` + - `"medium"` - The status of the apply patch tool call output. One of `completed` or `failed`. + - `"high"` - - `"completed"` + - `"auto"` - - `"failed"` + - `size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or "auto"` - - `type: "apply_patch_call_output"` + The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. - The type of the item. Always `apply_patch_call_output`. + - `string` - - `"apply_patch_call_output"` + - `"1024x1024" or "1024x1536" or "1536x1024" or "auto"` - - `id: optional string` + The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. - The unique ID of the apply patch tool call output. Populated when this item is returned via API. + - `"1024x1024"` - - `output: optional string` + - `"1024x1536"` - Optional human-readable log text from the apply patch tool (e.g., patch results or errors). + - `"1536x1024"` - - `McpListTools object { id, server_label, tools, 2 more }` + - `"auto"` - A list of tools available on an MCP server. + - `LocalShell object { type }` - - `id: string` + A tool that allows the model to execute shell commands in a local environment. - The unique ID of the list. + - `type: "local_shell"` - - `server_label: string` + The type of the local shell tool. Always `local_shell`. - The label of the MCP server. + - `"local_shell"` - - `tools: array of object { input_schema, name, annotations, description }` + - `Shell object { type, environment }` - The tools available on the server. + A tool that allows the model to execute shell commands. - - `input_schema: unknown` + - `type: "shell"` - The JSON schema describing the tool's input. + The type of the shell tool. Always `shell`. - - `name: string` + - `"shell"` - The name of the tool. + - `environment: optional ContainerAuto or LocalEnvironment or ContainerReference` - - `annotations: optional unknown` + - `ContainerAuto object { type, file_ids, memory_limit, 2 more }` - Additional annotations about the tool. + - `LocalEnvironment object { type, skills }` - - `description: optional string` + - `ContainerReference object { container_id, type }` - The description of the tool. + - `Custom object { name, type, defer_loading, 2 more }` - - `type: "mcp_list_tools"` + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) - The type of the item. Always `mcp_list_tools`. + - `name: string` - - `"mcp_list_tools"` + The name of the custom tool, used to identify it in tool calls. - - `error: optional string` + - `type: "custom"` - Error message if the server could not list tools. + The type of the custom tool. Always `custom`. - - `McpApprovalRequest object { id, arguments, name, 2 more }` + - `"custom"` - A request for human approval of a tool invocation. + - `defer_loading: optional boolean` - - `id: string` + Whether this tool should be deferred and discovered via tool search. - The unique ID of the approval request. + - `description: optional string` - - `arguments: string` + Optional description of the custom tool, used to provide more context. - A JSON string of arguments for the tool. + - `format: optional CustomToolInputFormat` - - `name: string` + The input format for the custom tool. Default is unconstrained text. - The name of the tool to run. + - `Namespace object { description, name, tools, type }` - - `server_label: string` + Groups function/custom tools under a shared namespace. - The label of the MCP server making the request. + - `description: string` - - `type: "mcp_approval_request"` + A description of the namespace shown to the model. - The type of the item. Always `mcp_approval_request`. + - `name: string` - - `"mcp_approval_request"` + The namespace name used in tool calls (for example, `crm`). - - `McpApprovalResponse object { approval_request_id, approve, type, 2 more }` + - `tools: array of object { name, type, defer_loading, 3 more } or object { name, type, defer_loading, 2 more }` - A response to an MCP approval request. + The function/custom tools available inside this namespace. - - `approval_request_id: string` + - `Function object { name, type, defer_loading, 3 more }` - The ID of the approval request being answered. + - `name: string` - - `approve: boolean` + - `type: "function"` - Whether the request was approved. + - `"function"` - - `type: "mcp_approval_response"` + - `defer_loading: optional boolean` - The type of the item. Always `mcp_approval_response`. + Whether this function should be deferred and discovered via tool search. - - `"mcp_approval_response"` + - `description: optional string` - - `id: optional string` + - `parameters: optional unknown` - The unique ID of the approval response + - `strict: optional boolean` - - `reason: optional string` + - `Custom object { name, type, defer_loading, 2 more }` - Optional reason for the decision. + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) - - `McpCall object { id, arguments, name, 6 more }` + - `name: string` - An invocation of a tool on an MCP server. + The name of the custom tool, used to identify it in tool calls. - - `id: string` + - `type: "custom"` - The unique ID of the tool call. + The type of the custom tool. Always `custom`. - - `arguments: string` + - `"custom"` - A JSON string of the arguments passed to the tool. + - `defer_loading: optional boolean` - - `name: string` + Whether this tool should be deferred and discovered via tool search. - The name of the tool that was run. + - `description: optional string` - - `server_label: string` + Optional description of the custom tool, used to provide more context. - The label of the MCP server running the tool. + - `format: optional CustomToolInputFormat` - - `type: "mcp_call"` + The input format for the custom tool. Default is unconstrained text. - The type of the item. Always `mcp_call`. + - `type: "namespace"` - - `"mcp_call"` + The type of the tool. Always `namespace`. - - `approval_request_id: optional string` + - `"namespace"` - Unique identifier for the MCP tool call approval request. - Include this value in a subsequent `mcp_approval_response` input to approve or reject the corresponding tool call. + - `ToolSearch object { type, description, execution, parameters }` - - `error: optional string` + Hosted or BYOT tool search configuration for deferred tools. - The error from the tool call, if any. + - `type: "tool_search"` - - `output: optional string` + The type of the tool. Always `tool_search`. - The output from the tool call. + - `"tool_search"` - - `status: optional "in_progress" or "completed" or "incomplete" or 2 more` + - `description: optional string` - The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. + Description shown to the model for a client-executed tool search tool. - - `"in_progress"` + - `execution: optional "server" or "client"` - - `"completed"` + Whether tool search is executed by the server or by the client. - - `"incomplete"` + - `"server"` - - `"calling"` + - `"client"` - - `"failed"` + - `parameters: optional unknown` - - `CustomToolCallOutput object { call_id, output, type, id }` + Parameter schema for a client-executed tool search tool. - The output of a custom tool call from your code, being sent back to the model. + - `WebSearchPreview object { type, search_content_types, search_context_size, user_location }` - - `call_id: string` + This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - The call ID, used to map this custom tool call output to a custom tool call. + - `type: "web_search_preview" or "web_search_preview_2025_03_11"` - - `output: string or array of ResponseInputText or ResponseInputImage or ResponseInputFile` + The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. - The output from the custom tool call generated by your code. - Can be a string or an list of output content. + - `"web_search_preview"` - - `StringOutput = string` + - `"web_search_preview_2025_03_11"` - A string of the output of the custom tool call. + - `search_content_types: optional array of "text" or "image"` - - `OutputContentList = array of ResponseInputText or ResponseInputImage or ResponseInputFile` + - `"text"` - Text, image, or file output of the custom tool call. + - `"image"` - - `ResponseInputText object { text, type }` + - `search_context_size: optional "low" or "medium" or "high"` - A text input to the model. + High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. - - `ResponseInputImage object { detail, type, file_id, image_url }` + - `"low"` - An image input to the model. Learn about [image inputs](/docs/guides/vision). + - `"medium"` - - `ResponseInputFile object { type, detail, file_data, 3 more }` + - `"high"` - A file input to the model. + - `user_location: optional object { type, city, country, 2 more }` - - `type: "custom_tool_call_output"` + The user's location. - The type of the custom tool call output. Always `custom_tool_call_output`. + - `type: "approximate"` - - `"custom_tool_call_output"` + The type of location approximation. Always `approximate`. - - `id: optional string` + - `"approximate"` - The unique ID of the custom tool call output in the OpenAI platform. + - `city: optional string` - - `CustomToolCall object { call_id, input, name, 3 more }` + Free text input for the city of the user, e.g. `San Francisco`. - A call to a custom tool created by the model. + - `country: optional string` - - `call_id: string` + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - An identifier used to map this custom tool call to a tool call output. + - `region: optional string` - - `input: string` + Free text input for the region of the user, e.g. `California`. - The input for the custom tool call generated by the model. + - `timezone: optional string` - - `name: string` + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - The name of the custom tool being called. + - `ApplyPatch object { type }` - - `type: "custom_tool_call"` + Allows the assistant to create, delete, or update files using unified diffs. - The type of the custom tool call. Always `custom_tool_call`. + - `type: "apply_patch"` - - `"custom_tool_call"` + The type of the tool. Always `apply_patch`. - - `id: optional string` + - `"apply_patch"` - The unique ID of the custom tool call in the OpenAI platform. + - `type: "additional_tools"` - - `namespace: optional string` + The item type. Always `additional_tools`. - The namespace of the custom tool being called. + - `"additional_tools"` - - `CompactionTrigger object { type }` + - `id: optional string` - Compacts the current context. Must be the final input item. + The unique ID of this additional tools item. - - `type: "compaction_trigger"` + - `Reasoning object { id, summary, type, 3 more }` - The type of the item. Always `compaction_trigger`. + 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). - - `"compaction_trigger"` + - `id: string` - - `ItemReference object { id, type }` + The unique identifier of the reasoning content. - An internal identifier for an item to reference. + - `summary: array of SummaryTextContent` - - `id: string` + Reasoning summary content. - The ID of the item to reference. + - `text: string` - - `type: optional "item_reference"` + A summary of the reasoning output from the model so far. + + - `type: "summary_text"` + + The type of the object. Always `summary_text`. + + - `"summary_text"` + + - `type: "reasoning"` + + The type of the object. Always `reasoning`. + + - `"reasoning"` + + - `content: optional array of object { text, type }` + + Reasoning text content. + + - `text: string` + + The reasoning text from the model. + + - `type: "reasoning_text"` + + The type of the reasoning text. Always `reasoning_text`. + + - `"reasoning_text"` + + - `encrypted_content: optional string` + + The encrypted content of the reasoning item - populated when a response is + generated with `reasoning.encrypted_content` in the `include` parameter. + + - `status: optional "in_progress" or "completed" or "incomplete"` + + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `Compaction object { encrypted_content, type, id }` + + A compaction item generated by the [`v1/responses/compact` API](/docs/api-reference/responses/compact). + + - `encrypted_content: string` + + The encrypted content of the compaction summary. + + - `type: "compaction"` + + The type of the item. Always `compaction`. + + - `"compaction"` + + - `id: optional string` + + The ID of the compaction item. + + - `ImageGenerationCall object { id, result, status, type }` + + An image generation request made by the model. + + - `id: string` + + The unique ID of the image generation call. + + - `result: string` + + The generated image encoded in base64. + + - `status: "in_progress" or "completed" or "generating" or "failed"` + + The status of the image generation call. + + - `"in_progress"` + + - `"completed"` + + - `"generating"` + + - `"failed"` + + - `type: "image_generation_call"` + + The type of the image generation call. Always `image_generation_call`. + + - `"image_generation_call"` + + - `CodeInterpreterCall object { id, code, container_id, 3 more }` + + A tool call to run code. + + - `id: string` + + The unique ID of the code interpreter tool call. + + - `code: string` + + The code to run, or null if not available. + + - `container_id: string` + + The ID of the container used to run the code. + + - `outputs: array of object { logs, type } or object { type, url }` + + The outputs generated by the code interpreter, such as logs or images. + Can be null if no outputs are available. + + - `Logs object { logs, type }` + + The logs output from the code interpreter. + + - `logs: string` + + The logs output from the code interpreter. + + - `type: "logs"` + + The type of the output. Always `logs`. + + - `"logs"` + + - `Image object { type, url }` + + The image output from the code interpreter. + + - `type: "image"` + + The type of the output. Always `image`. + + - `"image"` + + - `url: string` + + The URL of the image output from the code interpreter. + + - `status: "in_progress" or "completed" or "incomplete" or 2 more` + + The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `"interpreting"` + + - `"failed"` + + - `type: "code_interpreter_call"` + + The type of the code interpreter tool call. Always `code_interpreter_call`. + + - `"code_interpreter_call"` + + - `LocalShellCall object { id, action, call_id, 2 more }` + + A tool call to run a command on the local shell. + + - `id: string` + + The unique ID of the local shell call. + + - `action: object { command, env, type, 3 more }` + + Execute a shell command on the server. + + - `command: array of string` + + The command to run. + + - `env: map[string]` + + Environment variables to set for the command. + + - `type: "exec"` + + The type of the local shell action. Always `exec`. + + - `"exec"` + + - `timeout_ms: optional number` + + Optional timeout in milliseconds for the command. + + - `user: optional string` + + Optional user to run the command as. + + - `working_directory: optional string` + + Optional working directory to run the command in. + + - `call_id: string` + + The unique ID of the local shell tool call generated by the model. + + - `status: "in_progress" or "completed" or "incomplete"` + + The status of the local shell call. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `type: "local_shell_call"` + + The type of the local shell call. Always `local_shell_call`. + + - `"local_shell_call"` + + - `LocalShellCallOutput object { id, output, type, status }` + + The output of a local shell tool call. + + - `id: string` + + The unique ID of the local shell tool call generated by the model. + + - `output: string` + + A JSON string of the output of the local shell tool call. + + - `type: "local_shell_call_output"` + + The type of the local shell tool call output. Always `local_shell_call_output`. + + - `"local_shell_call_output"` + + - `status: optional "in_progress" or "completed" or "incomplete"` + + The status of the item. One of `in_progress`, `completed`, or `incomplete`. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `ShellCall object { action, call_id, type, 3 more }` + + A tool representing a request to execute one or more shell commands. + + - `action: object { commands, max_output_length, timeout_ms }` + + The shell commands and limits that describe how to run the tool call. + + - `commands: array of string` + + Ordered shell commands for the execution environment to run. + + - `max_output_length: optional number` + + Maximum number of UTF-8 characters to capture from combined stdout and stderr output. + + - `timeout_ms: optional number` + + Maximum wall-clock time in milliseconds to allow the shell commands to run. + + - `call_id: string` + + The unique ID of the shell tool call generated by the model. + + - `type: "shell_call"` + + The type of the item. Always `shell_call`. + + - `"shell_call"` + + - `id: optional string` + + The unique ID of the shell tool call. Populated when this item is returned via API. + + - `environment: optional LocalEnvironment or ContainerReference` + + The environment to execute the shell commands in. + + - `LocalEnvironment object { type, skills }` + + - `ContainerReference object { container_id, type }` + + - `status: optional "in_progress" or "completed" or "incomplete"` + + The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `ShellCallOutput object { call_id, output, type, 3 more }` + + The streamed output items emitted by a shell tool call. + + - `call_id: string` + + The unique ID of the shell tool call generated by the model. + + - `output: array of ResponseFunctionShellCallOutputContent` + + Captured chunks of stdout and stderr output, along with their associated outcomes. + + - `outcome: object { type } or object { exit_code, type }` + + The exit or timeout outcome associated with this shell call. + + - `Timeout object { type }` + + Indicates that the shell call exceeded its configured time limit. + + - `type: "timeout"` + + The outcome type. Always `timeout`. + + - `"timeout"` + + - `Exit object { exit_code, type }` + + Indicates that the shell commands finished and returned an exit code. + + - `exit_code: number` + + The exit code returned by the shell process. + + - `type: "exit"` + + The outcome type. Always `exit`. + + - `"exit"` + + - `stderr: string` + + Captured stderr output for the shell call. + + - `stdout: string` + + Captured stdout output for the shell call. + + - `type: "shell_call_output"` + + The type of the item. Always `shell_call_output`. + + - `"shell_call_output"` + + - `id: optional string` + + The unique ID of the shell tool call output. Populated when this item is returned via API. + + - `max_output_length: optional number` + + The maximum number of UTF-8 characters captured for this shell call's combined output. + + - `status: optional "in_progress" or "completed" or "incomplete"` + + The status of the shell call output. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `ApplyPatchCall object { call_id, operation, status, 2 more }` + + A tool call representing a request to create, delete, or update files using diff patches. + + - `call_id: string` + + The unique ID of the apply patch tool call generated by the model. + + - `operation: object { diff, path, type } or object { path, type } or object { diff, path, type }` + + The specific create, delete, or update instruction for the apply_patch tool call. + + - `CreateFile object { diff, path, type }` + + Instruction for creating a new file via the apply_patch tool. + + - `diff: string` + + Unified diff content to apply when creating the file. + + - `path: string` + + Path of the file to create relative to the workspace root. + + - `type: "create_file"` + + The operation type. Always `create_file`. + + - `"create_file"` + + - `DeleteFile object { path, type }` + + Instruction for deleting an existing file via the apply_patch tool. + + - `path: string` + + Path of the file to delete relative to the workspace root. + + - `type: "delete_file"` + + The operation type. Always `delete_file`. + + - `"delete_file"` + + - `UpdateFile object { diff, path, type }` + + Instruction for updating an existing file via the apply_patch tool. + + - `diff: string` + + Unified diff content to apply to the existing file. + + - `path: string` + + Path of the file to update relative to the workspace root. + + - `type: "update_file"` + + The operation type. Always `update_file`. + + - `"update_file"` + + - `status: "in_progress" or "completed"` + + The status of the apply patch tool call. One of `in_progress` or `completed`. + + - `"in_progress"` + + - `"completed"` + + - `type: "apply_patch_call"` + + The type of the item. Always `apply_patch_call`. + + - `"apply_patch_call"` + + - `id: optional string` + + 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 }` + + The streamed output emitted by an apply patch tool call. + + - `call_id: string` + + The unique ID of the apply patch tool call generated by the model. + + - `status: "completed" or "failed"` + + The status of the apply patch tool call output. One of `completed` or `failed`. + + - `"completed"` + + - `"failed"` + + - `type: "apply_patch_call_output"` + + The type of the item. Always `apply_patch_call_output`. + + - `"apply_patch_call_output"` + + - `id: optional string` + + The unique ID of the apply patch tool call output. Populated when this item is returned via API. + + - `output: optional string` + + Optional human-readable log text from the apply patch tool (e.g., patch results or errors). + + - `McpListTools object { id, server_label, tools, 2 more }` + + A list of tools available on an MCP server. + + - `id: string` + + The unique ID of the list. + + - `server_label: string` + + The label of the MCP server. + + - `tools: array of object { input_schema, name, annotations, description }` + + The tools available on the server. + + - `input_schema: unknown` + + The JSON schema describing the tool's input. + + - `name: string` + + The name of the tool. + + - `annotations: optional unknown` + + Additional annotations about the tool. + + - `description: optional string` + + The description of the tool. + + - `type: "mcp_list_tools"` + + The type of the item. Always `mcp_list_tools`. + + - `"mcp_list_tools"` + + - `error: optional string` + + Error message if the server could not list tools. + + - `McpApprovalRequest object { id, arguments, name, 2 more }` + + A request for human approval of a tool invocation. + + - `id: string` + + The unique ID of the approval request. + + - `arguments: string` + + A JSON string of arguments for the tool. + + - `name: string` + + The name of the tool to run. + + - `server_label: string` + + The label of the MCP server making the request. + + - `type: "mcp_approval_request"` + + The type of the item. Always `mcp_approval_request`. + + - `"mcp_approval_request"` + + - `McpApprovalResponse object { approval_request_id, approve, type, 2 more }` + + A response to an MCP approval request. + + - `approval_request_id: string` + + The ID of the approval request being answered. + + - `approve: boolean` + + Whether the request was approved. + + - `type: "mcp_approval_response"` + + The type of the item. Always `mcp_approval_response`. + + - `"mcp_approval_response"` + + - `id: optional string` + + The unique ID of the approval response + + - `reason: optional string` + + Optional reason for the decision. + + - `McpCall object { id, arguments, name, 6 more }` + + An invocation of a tool on an MCP server. + + - `id: string` + + The unique ID of the tool call. + + - `arguments: string` + + A JSON string of the arguments passed to the tool. + + - `name: string` + + The name of the tool that was run. + + - `server_label: string` + + The label of the MCP server running the tool. + + - `type: "mcp_call"` + + The type of the item. Always `mcp_call`. + + - `"mcp_call"` + + - `approval_request_id: optional string` + + Unique identifier for the MCP tool call approval request. + Include this value in a subsequent `mcp_approval_response` input to approve or reject the corresponding tool call. + + - `error: optional string` + + The error from the tool call, if any. + + - `output: optional string` + + The output from the tool call. + + - `status: optional "in_progress" or "completed" or "incomplete" or 2 more` + + The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `"calling"` + + - `"failed"` + + - `CustomToolCallOutput object { call_id, output, type, id }` + + The output of a custom tool call from your code, being sent back to the model. + + - `call_id: string` + + The call ID, used to map this custom tool call output to a custom tool call. + + - `output: string or array of ResponseInputText or ResponseInputImage or ResponseInputFile` + + The output from the custom tool call generated by your code. + Can be a string or an list of output content. + + - `StringOutput = string` + + A string of the output of the custom tool call. + + - `OutputContentList = array of ResponseInputText or ResponseInputImage or ResponseInputFile` + + Text, image, or file output of the custom tool call. + + - `ResponseInputText object { text, type }` + + A text input to the model. + + - `ResponseInputImage object { detail, type, file_id, image_url }` + + An image input to the model. Learn about [image inputs](/docs/guides/vision). + + - `ResponseInputFile object { type, detail, file_data, 3 more }` + + A file input to the model. + + - `type: "custom_tool_call_output"` + + The type of the custom tool call output. Always `custom_tool_call_output`. + + - `"custom_tool_call_output"` + + - `id: optional string` + + The unique ID of the custom tool call output in the OpenAI platform. + + - `CustomToolCall object { call_id, input, name, 3 more }` + + A call to a custom tool created by the model. + + - `call_id: string` + + An identifier used to map this custom tool call to a tool call output. + + - `input: string` + + The input for the custom tool call generated by the model. + + - `name: string` + + The name of the custom tool being called. + + - `type: "custom_tool_call"` + + The type of the custom tool call. Always `custom_tool_call`. + + - `"custom_tool_call"` + + - `id: optional string` + + The unique ID of the custom tool call in the OpenAI platform. + + - `namespace: optional string` + + The namespace of the custom tool being called. + + - `CompactionTrigger object { type }` + + Compacts the current context. Must be the final input item. + + - `type: "compaction_trigger"` + + The type of the item. Always `compaction_trigger`. + + - `"compaction_trigger"` + + - `ItemReference object { id, type }` + + An internal identifier for an item to reference. + + - `id: string` + + The ID of the item to reference. + + - `type: optional "item_reference"` + + The type of item to reference. Always `item_reference`. + + - `"item_reference"` + +- `metadata: optional Metadata` + + Set of 16 key-value pairs that can be attached to an object. This can be + useful for storing additional information about the object in a structured + format, and querying for objects via API or the dashboard. + + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. + +### Returns + +- `Conversation object { id, created_at, metadata, object }` + + - `id: string` + + The unique ID of the conversation. + + - `created_at: number` + + The time at which the conversation was created, measured in seconds since the Unix epoch. + + - `metadata: unknown` + + Set of 16 key-value pairs that can be attached to an object. This can be useful for storing additional information about the object in a structured format, and querying for objects via API or the dashboard. + Keys are strings with a maximum length of 64 characters. Values are strings with a maximum length of 512 characters. + + - `object: "conversation"` + + The object type, which is always `conversation`. + + - `"conversation"` + +### Example + +```http +curl https://api.openai.com/v1/conversations \ + -X POST \ + -H "Authorization: Bearer $OPENAI_API_KEY" +``` + +#### Response + +```json +{ + "id": "id", + "created_at": 0, + "metadata": {}, + "object": "conversation" +} +``` + +### Example + +```http +curl https://api.openai.com/v1/conversations \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -d '{ + "metadata": {"topic": "demo"}, + "items": [ + { + "type": "message", + "role": "user", + "content": "Hello!" + } + ] + }' +``` + +#### Response + +```json +{ + "id": "conv_123", + "object": "conversation", + "created_at": 1741900000, + "metadata": {"topic": "demo"} +} +``` + +## Retrieve a conversation + +**get** `/conversations/{conversation_id}` + +Get a conversation + +### Path Parameters + +- `conversation_id: string` + +### Returns + +- `Conversation object { id, created_at, metadata, object }` + + - `id: string` + + The unique ID of the conversation. + + - `created_at: number` + + The time at which the conversation was created, measured in seconds since the Unix epoch. + + - `metadata: unknown` + + Set of 16 key-value pairs that can be attached to an object. This can be useful for storing additional information about the object in a structured format, and querying for objects via API or the dashboard. + Keys are strings with a maximum length of 64 characters. Values are strings with a maximum length of 512 characters. + + - `object: "conversation"` + + The object type, which is always `conversation`. + + - `"conversation"` + +### Example + +```http +curl https://api.openai.com/v1/conversations/$CONVERSATION_ID \ + -H "Authorization: Bearer $OPENAI_API_KEY" +``` + +#### Response + +```json +{ + "id": "id", + "created_at": 0, + "metadata": {}, + "object": "conversation" +} +``` + +### Example + +```http +curl https://api.openai.com/v1/conversations/conv_123 \ + -H "Authorization: Bearer $OPENAI_API_KEY" +``` + +#### Response + +```json +{ + "id": "conv_123", + "object": "conversation", + "created_at": 1741900000, + "metadata": {"topic": "demo"} +} +``` + +## Update a conversation + +**post** `/conversations/{conversation_id}` + +Update a conversation + +### Path Parameters + +- `conversation_id: string` + +### Body Parameters + +- `metadata: Metadata` + + Set of 16 key-value pairs that can be attached to an object. This can be + useful for storing additional information about the object in a structured + format, and querying for objects via API or the dashboard. + + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. + +### Returns + +- `Conversation object { id, created_at, metadata, object }` + + - `id: string` + + The unique ID of the conversation. + + - `created_at: number` + + The time at which the conversation was created, measured in seconds since the Unix epoch. + + - `metadata: unknown` + + Set of 16 key-value pairs that can be attached to an object. This can be useful for storing additional information about the object in a structured format, and querying for objects via API or the dashboard. + Keys are strings with a maximum length of 64 characters. Values are strings with a maximum length of 512 characters. + + - `object: "conversation"` + + The object type, which is always `conversation`. + + - `"conversation"` + +### Example + +```http +curl https://api.openai.com/v1/conversations/$CONVERSATION_ID \ + -H 'Content-Type: application/json' \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -d '{ + "metadata": { + "foo": "string" + } + }' +``` + +#### Response + +```json +{ + "id": "id", + "created_at": 0, + "metadata": {}, + "object": "conversation" +} +``` + +### Example + +```http +curl https://api.openai.com/v1/conversations/conv_123 \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -d '{ + "metadata": {"topic": "project-x"} + }' +``` + +#### Response + +```json +{ + "id": "conv_123", + "object": "conversation", + "created_at": 1741900000, + "metadata": {"topic": "project-x"} +} +``` + +## Delete a conversation + +**delete** `/conversations/{conversation_id}` + +Delete a conversation. Items in the conversation will not be deleted. + +### Path Parameters + +- `conversation_id: string` + +### Returns + +- `ConversationDeletedResource object { id, deleted, object }` + + - `id: string` + + - `deleted: boolean` + + - `object: "conversation.deleted"` + + - `"conversation.deleted"` + +### Example + +```http +curl https://api.openai.com/v1/conversations/$CONVERSATION_ID \ + -X DELETE \ + -H "Authorization: Bearer $OPENAI_API_KEY" +``` + +#### Response + +```json +{ + "id": "id", + "deleted": true, + "object": "conversation.deleted" +} +``` + +### Example + +```http +curl -X DELETE https://api.openai.com/v1/conversations/conv_123 \ + -H "Authorization: Bearer $OPENAI_API_KEY" +``` + +#### Response + +```json +{ + "id": "conv_123", + "object": "conversation.deleted", + "deleted": true +} +``` + +## Domain Types + +### Computer Screenshot Content + +- `ComputerScreenshotContent object { detail, file_id, image_url, type }` + + A screenshot of a computer. + + - `detail: "low" or "high" or "auto" or "original"` + + The detail level of the screenshot image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + + - `"low"` + + - `"high"` + + - `"auto"` + + - `"original"` + + - `file_id: string` + + The identifier of an uploaded file that contains the screenshot. + + - `image_url: string` + + The URL of the screenshot image. + + - `type: "computer_screenshot"` + + Specifies the event type. For a computer screenshot, this property is always set to `computer_screenshot`. + + - `"computer_screenshot"` + +### Conversation + +- `Conversation object { id, created_at, metadata, object }` + + - `id: string` + + The unique ID of the conversation. + + - `created_at: number` + + The time at which the conversation was created, measured in seconds since the Unix epoch. + + - `metadata: unknown` + + Set of 16 key-value pairs that can be attached to an object. This can be useful for storing additional information about the object in a structured format, and querying for objects via API or the dashboard. + Keys are strings with a maximum length of 64 characters. Values are strings with a maximum length of 512 characters. + + - `object: "conversation"` + + The object type, which is always `conversation`. + + - `"conversation"` + +### Conversation Deleted + +- `ConversationDeleted object { id, deleted, object }` + + - `id: string` + + - `deleted: boolean` + + - `object: "conversation.deleted"` + + - `"conversation.deleted"` + +### Conversation Deleted Resource + +- `ConversationDeletedResource object { id, deleted, object }` + + - `id: string` + + - `deleted: boolean` + + - `object: "conversation.deleted"` + + - `"conversation.deleted"` + +### Message + +- `Message object { id, content, role, 3 more }` + + A message to or from the model. + + - `id: string` + + The unique ID of the message. + + - `content: array of ResponseInputText or ResponseOutputText or TextContent or 6 more` + + The content of the message + + - `ResponseInputText object { text, type }` + + A text input to the model. + + - `text: string` + + The text input to the model. + + - `type: "input_text"` + + The type of the input item. Always `input_text`. + + - `"input_text"` + + - `ResponseOutputText object { annotations, logprobs, text, type }` + + A text output from the model. + + - `annotations: array of object { file_id, filename, index, type } or object { end_index, start_index, title, 2 more } or object { container_id, end_index, file_id, 3 more } or object { file_id, index, type }` + + The annotations of the text output. + + - `FileCitation object { file_id, filename, index, type }` + + A citation to a file. + + - `file_id: string` + + The ID of the file. + + - `filename: string` + + The filename of the file cited. + + - `index: number` + + The index of the file in the list of files. + + - `type: "file_citation"` + + The type of the file citation. Always `file_citation`. + + - `"file_citation"` + + - `URLCitation object { end_index, start_index, title, 2 more }` + + A citation for a web resource used to generate a model response. + + - `end_index: number` + + The index of the last character of the URL citation in the message. + + - `start_index: number` + + The index of the first character of the URL citation in the message. + + - `title: string` + + The title of the web resource. + + - `type: "url_citation"` + + The type of the URL citation. Always `url_citation`. + + - `"url_citation"` + + - `url: string` + + The URL of the web resource. + + - `ContainerFileCitation object { container_id, end_index, file_id, 3 more }` + + A citation for a container file used to generate a model response. + + - `container_id: string` + + The ID of the container file. + + - `end_index: number` + + The index of the last character of the container file citation in the message. + + - `file_id: string` + + The ID of the file. + + - `filename: string` + + The filename of the container file cited. + + - `start_index: number` + + The index of the first character of the container file citation in the message. + + - `type: "container_file_citation"` + + The type of the container file citation. Always `container_file_citation`. + + - `"container_file_citation"` + + - `FilePath object { file_id, index, type }` + + A path to a file. + + - `file_id: string` + + The ID of the file. + + - `index: number` + + The index of the file in the list of files. + + - `type: "file_path"` + + The type of the file path. Always `file_path`. + + - `"file_path"` + + - `logprobs: array of object { token, bytes, logprob, top_logprobs }` + + - `token: string` + + - `bytes: array of number` + + - `logprob: number` + + - `top_logprobs: array of object { token, bytes, logprob }` + + - `token: string` + + - `bytes: array of number` + + - `logprob: number` + + - `text: string` + + The text output from the model. + + - `type: "output_text"` + + The type of the output text. Always `output_text`. + + - `"output_text"` + + - `TextContent object { text, type }` + + A text content. + + - `text: string` + + - `type: "text"` + + - `"text"` + + - `SummaryTextContent object { text, type }` + + A summary text from the model. + + - `text: string` + + A summary of the reasoning output from the model so far. + + - `type: "summary_text"` + + The type of the object. Always `summary_text`. + + - `"summary_text"` + + - `ReasoningText object { text, type }` + + Reasoning text from the model. + + - `text: string` + + The reasoning text from the model. + + - `type: "reasoning_text"` + + The type of the reasoning text. Always `reasoning_text`. + + - `"reasoning_text"` + + - `ResponseOutputRefusal object { refusal, type }` + + A refusal from the model. + + - `refusal: string` + + The refusal explanation from the model. + + - `type: "refusal"` + + The type of the refusal. Always `refusal`. + + - `"refusal"` + + - `ResponseInputImage object { detail, type, file_id, image_url }` + + An image input to the model. Learn about [image inputs](/docs/guides/vision). + + - `detail: "low" or "high" or "auto" or "original"` + + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + + - `"low"` + + - `"high"` + + - `"auto"` + + - `"original"` + + - `type: "input_image"` + + The type of the input item. Always `input_image`. + + - `"input_image"` + + - `file_id: optional string` + + The ID of the file to be sent to the model. + + - `image_url: optional string` + + 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 }` + + A screenshot of a computer. + + - `detail: "low" or "high" or "auto" or "original"` + + The detail level of the screenshot image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + + - `"low"` + + - `"high"` + + - `"auto"` + + - `"original"` + + - `file_id: string` + + The identifier of an uploaded file that contains the screenshot. + + - `image_url: string` + + The URL of the screenshot image. + + - `type: "computer_screenshot"` + + Specifies the event type. For a computer screenshot, this property is always set to `computer_screenshot`. + + - `"computer_screenshot"` + + - `ResponseInputFile object { type, detail, file_data, 3 more }` + + A file input to the model. + + - `type: "input_file"` + + The type of the input item. Always `input_file`. + + - `"input_file"` + + - `detail: optional "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`. + + - `"low"` + + - `"high"` + + - `file_data: optional string` + + The content of the file to be sent to the model. + + - `file_id: optional string` + + The ID of the file to be sent to the model. + + - `file_url: optional string` + + The URL of the file to be sent to the model. + + - `filename: optional string` + + The name of the file to be sent to the model. + + - `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`. + + - `"unknown"` + + - `"user"` + + - `"assistant"` + + - `"system"` + + - `"critic"` + + - `"discriminator"` + + - `"developer"` + + - `"tool"` + + - `status: "in_progress" or "completed" or "incomplete"` + + The status of item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `type: "message"` + + The type of the message. Always set to `message`. + + - `"message"` + + - `phase: optional "commentary" or "final_answer"` + + Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend phase on all assistant messages — dropping it can degrade performance. Not used for user messages. + + - `"commentary"` + + - `"final_answer"` + +### Summary Text Content + +- `SummaryTextContent object { text, type }` + + A summary text from the model. + + - `text: string` + + A summary of the reasoning output from the model so far. + + - `type: "summary_text"` + + The type of the object. Always `summary_text`. + + - `"summary_text"` + +### Text Content + +- `TextContent object { text, type }` + + A text content. + + - `text: string` + + - `type: "text"` + + - `"text"` + +# Items + +## Create items + +**post** `/conversations/{conversation_id}/items` + +Create items in a conversation with the given ID. + +### Path Parameters + +- `conversation_id: string` + +### Query Parameters + +- `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. + + - `"file_search_call.results"` + + - `"web_search_call.results"` + + - `"web_search_call.action.sources"` + + - `"message.input_image.image_url"` + + - `"computer_call_output.output.image_url"` + + - `"code_interpreter_call.outputs"` + + - `"reasoning.encrypted_content"` + + - `"message.output_text.logprobs"` + +### Body Parameters + +- `items: array of EasyInputMessage or object { content, role, status, type } or ResponseOutputMessage or 27 more` + + The items to add to the conversation. You may add up to 20 items at a time. + + - `EasyInputMessage object { content, role, phase, type }` + + A message input to the model with a role indicating instruction following + hierarchy. Instructions given with the `developer` or `system` role take + precedence over instructions given with the `user` role. Messages with the + `assistant` role are presumed to have been generated by the model in previous + interactions. + + - `content: string or ResponseInputMessageContentList` + + Text, image, or audio input to the model, used to generate a response. + Can also contain previous assistant responses. + + - `TextInput = string` + + A text input to the model. + + - `ResponseInputMessageContentList = array of ResponseInputContent` + + A list of one or many input items to the model, containing different content + types. + + - `ResponseInputText object { text, type }` + + A text input to the model. + + - `text: string` + + The text input to the model. + + - `type: "input_text"` + + The type of the input item. Always `input_text`. + + - `"input_text"` + + - `ResponseInputImage object { detail, type, file_id, image_url }` + + An image input to the model. Learn about [image inputs](/docs/guides/vision). + + - `detail: "low" or "high" or "auto" or "original"` + + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + + - `"low"` + + - `"high"` + + - `"auto"` + + - `"original"` + + - `type: "input_image"` + + The type of the input item. Always `input_image`. + + - `"input_image"` + + - `file_id: optional string` + + The ID of the file to be sent to the model. + + - `image_url: optional string` + + 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 }` + + A file input to the model. + + - `type: "input_file"` + + The type of the input item. Always `input_file`. + + - `"input_file"` + + - `detail: optional "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`. + + - `"low"` + + - `"high"` + + - `file_data: optional string` + + The content of the file to be sent to the model. + + - `file_id: optional string` + + The ID of the file to be sent to the model. + + - `file_url: optional string` + + The URL of the file to be sent to the model. + + - `filename: optional string` + + The name of the file to be sent to the model. + + - `role: "user" or "assistant" or "system" or "developer"` + + The role of the message input. One of `user`, `assistant`, `system`, or + `developer`. + + - `"user"` + + - `"assistant"` + + - `"system"` + + - `"developer"` + + - `phase: optional "commentary" or "final_answer"` + + Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). + For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend + phase on all assistant messages — dropping it can degrade performance. Not used for user messages. + + - `"commentary"` + + - `"final_answer"` + + - `type: optional "message"` + + The type of the message input. Always `message`. + + - `"message"` + + - `Message object { content, role, status, type }` + + A message input to the model with a role indicating instruction following + hierarchy. Instructions given with the `developer` or `system` role take + precedence over instructions given with the `user` role. + + - `content: ResponseInputMessageContentList` + + A list of one or many input items to the model, containing different content + types. + + - `role: "user" or "system" or "developer"` + + The role of the message input. One of `user`, `system`, or `developer`. + + - `"user"` + + - `"system"` + + - `"developer"` + + - `status: optional "in_progress" or "completed" or "incomplete"` + + The status of item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `type: optional "message"` + + The type of the message input. Always set to `message`. + + - `"message"` + + - `ResponseOutputMessage object { id, content, role, 3 more }` + + An output message from the model. + + - `id: string` + + The unique ID of the output message. + + - `content: array of ResponseOutputText or ResponseOutputRefusal` + + The content of the output message. + + - `ResponseOutputText object { annotations, logprobs, text, type }` + + A text output from the model. + + - `annotations: array of object { file_id, filename, index, type } or object { end_index, start_index, title, 2 more } or object { container_id, end_index, file_id, 3 more } or object { file_id, index, type }` + + The annotations of the text output. + + - `FileCitation object { file_id, filename, index, type }` + + A citation to a file. + + - `file_id: string` + + The ID of the file. + + - `filename: string` + + The filename of the file cited. + + - `index: number` + + The index of the file in the list of files. + + - `type: "file_citation"` + + The type of the file citation. Always `file_citation`. + + - `"file_citation"` + + - `URLCitation object { end_index, start_index, title, 2 more }` + + A citation for a web resource used to generate a model response. + + - `end_index: number` + + The index of the last character of the URL citation in the message. + + - `start_index: number` + + The index of the first character of the URL citation in the message. + + - `title: string` + + The title of the web resource. + + - `type: "url_citation"` + + The type of the URL citation. Always `url_citation`. + + - `"url_citation"` + + - `url: string` + + The URL of the web resource. + + - `ContainerFileCitation object { container_id, end_index, file_id, 3 more }` + + A citation for a container file used to generate a model response. + + - `container_id: string` + + The ID of the container file. + + - `end_index: number` + + The index of the last character of the container file citation in the message. + + - `file_id: string` + + The ID of the file. + + - `filename: string` + + The filename of the container file cited. + + - `start_index: number` + + The index of the first character of the container file citation in the message. + + - `type: "container_file_citation"` + + The type of the container file citation. Always `container_file_citation`. + + - `"container_file_citation"` + + - `FilePath object { file_id, index, type }` + + A path to a file. + + - `file_id: string` + + The ID of the file. + + - `index: number` + + The index of the file in the list of files. + + - `type: "file_path"` + + The type of the file path. Always `file_path`. + + - `"file_path"` + + - `logprobs: array of object { token, bytes, logprob, top_logprobs }` + + - `token: string` + + - `bytes: array of number` + + - `logprob: number` + + - `top_logprobs: array of object { token, bytes, logprob }` + + - `token: string` + + - `bytes: array of number` + + - `logprob: number` + + - `text: string` + + The text output from the model. + + - `type: "output_text"` + + The type of the output text. Always `output_text`. + + - `"output_text"` + + - `ResponseOutputRefusal object { refusal, type }` + + A refusal from the model. + + - `refusal: string` + + The refusal explanation from the model. + + - `type: "refusal"` + + The type of the refusal. Always `refusal`. + + - `"refusal"` + + - `role: "assistant"` + + The role of the output message. Always `assistant`. + + - `"assistant"` + + - `status: "in_progress" or "completed" or "incomplete"` + + The status of the message input. One of `in_progress`, `completed`, or + `incomplete`. Populated when input items are returned via API. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `type: "message"` + + The type of the output message. Always `message`. + + - `"message"` + + - `phase: optional "commentary" or "final_answer"` + + Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). + For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend + phase on all assistant messages — dropping it can degrade performance. Not used for user messages. + + - `"commentary"` + + - `"final_answer"` + + - `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. + + - `id: string` + + The unique ID of the file search tool call. + + - `queries: array of string` + + The queries used to search for files. + + - `status: "in_progress" or "searching" or "completed" or 2 more` + + The status of the file search tool call. One of `in_progress`, + `searching`, `incomplete` or `failed`, + + - `"in_progress"` + + - `"searching"` + + - `"completed"` + + - `"incomplete"` + + - `"failed"` + + - `type: "file_search_call"` + + The type of the file search tool call. Always `file_search_call`. + + - `"file_search_call"` + + - `results: optional array of object { attributes, file_id, filename, 2 more }` + + The results of the file search tool call. + + - `attributes: optional map[string or number or boolean]` + + Set of 16 key-value pairs that can be attached to an object. This can be + useful for storing additional information about the object in a structured + format, and querying for objects via API or the dashboard. Keys are strings + with a maximum length of 64 characters. Values are strings with a maximum + length of 512 characters, booleans, or numbers. + + - `string` + + - `number` + + - `boolean` + + - `file_id: optional string` + + The unique ID of the file. + + - `filename: optional string` + + The name of the file. + + - `score: optional number` + + The relevance score of the file - a value between 0 and 1. + + - `text: optional string` + + The text that was retrieved from the file. + + - `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. + + - `id: string` + + The unique ID of the computer call. + + - `call_id: string` + + An identifier used when responding to the tool call with output. + + - `pending_safety_checks: array of object { id, code, message }` + + The pending safety checks for the computer call. + + - `id: string` + + The ID of the pending safety check. + + - `code: optional string` + + The type of the pending safety check. + + - `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 ComputerAction` + + A click action. + + - `Click object { button, type, x, 2 more }` + + A click action. + + - `button: "left" or "right" or "wheel" or 2 more` + + Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. + + - `"left"` + + - `"right"` + + - `"wheel"` + + - `"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"` + + - `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 { call_id, output, type, 3 more }` + + The output of a computer tool call. + + - `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. + + - `type: "computer_call_output"` + + The type of the computer tool call output. Always `computer_call_output`. + + - `"computer_call_output"` + + - `id: optional string` + + The ID of the computer tool 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. + + - `code: optional string` + + The type of the pending safety check. + + - `message: optional string` + + Details about the pending safety check. + + - `status: optional "in_progress" or "completed" or "incomplete"` + + The status of the message input. One of `in_progress`, `completed`, or `incomplete`. Populated when input items are returned via API. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `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. + + - `id: string` + + The unique ID of the web search tool call. + + - `action: object { type, queries, query, sources } or object { type, url } or object { pattern, type, url }` + + An object describing the specific action taken in this web search call. + Includes details on how the model used the web (search, open_page, find_in_page). + + - `Search object { type, queries, query, sources }` + + Action type "search" - Performs a web search query. + + - `type: "search"` + + The action type. + + - `"search"` + + - `queries: optional array of string` + + The search queries. + + - `query: optional string` + + The search query. + + - `sources: optional array of object { type, url }` + + The sources used in the search. + + - `type: "url"` + + The type of source. Always `url`. + + - `"url"` + + - `url: string` + + The URL of the source. + + - `OpenPage object { type, url }` + + Action type "open_page" - Opens a specific URL from search results. + + - `type: "open_page"` + + The action type. + + - `"open_page"` + + - `url: optional string` + + The URL opened by the model. + + - `FindInPage object { pattern, type, url }` + + Action type "find_in_page": Searches for a pattern within a loaded page. + + - `pattern: string` + + The pattern or text to search for within the page. + + - `type: "find_in_page"` + + The action type. + + - `"find_in_page"` + + - `url: string` + + The URL of the page searched for the pattern. + + - `status: "in_progress" or "searching" or "completed" or "failed"` + + The status of the web search tool call. + + - `"in_progress"` + + - `"searching"` + + - `"completed"` + + - `"failed"` + + - `type: "web_search_call"` + + The type of the web search tool call. Always `web_search_call`. + + - `"web_search_call"` + + - `FunctionCall object { arguments, call_id, name, 4 more }` + + A tool call to run a function. See the + [function calling guide](/docs/guides/function-calling) for more information. + + - `arguments: string` + + A JSON string of the arguments to pass to the function. + + - `call_id: string` + + The unique ID of the function tool call generated by the model. + + - `name: string` + + The name of the function to run. + + - `type: "function_call"` + + The type of the function tool call. Always `function_call`. + + - `"function_call"` + + - `id: optional string` + + The unique ID of the function tool call. + + - `namespace: optional string` + + The namespace of the function to run. + + - `status: optional "in_progress" or "completed" or "incomplete"` + + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `FunctionCallOutput object { call_id, output, type, 2 more }` + + The output of a function tool call. + + - `call_id: string` + + The unique ID of the function tool call generated by the model. + + - `output: string or array of ResponseInputTextContent or ResponseInputImageContent or ResponseInputFileContent` + + Text, image, or file output of the function tool call. + + - `string` + + A JSON string of the output of the function tool call. + + - `array of ResponseInputTextContent or ResponseInputImageContent or ResponseInputFileContent` + + An array of content outputs (text, image, file) for the function tool call. + + - `ResponseInputTextContent object { text, type }` + + A text input to the model. + + - `text: string` + + The text input to the model. + + - `type: "input_text"` + + The type of the input item. Always `input_text`. + + - `"input_text"` + + - `ResponseInputImageContent object { type, detail, file_id, image_url }` + + An image input to the model. Learn about [image inputs](/docs/guides/vision) + + - `type: "input_image"` + + The type of the input item. Always `input_image`. + + - `"input_image"` + + - `detail: optional "low" or "high" or "auto" or "original"` + + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + + - `"low"` + + - `"high"` + + - `"auto"` + + - `"original"` + + - `file_id: optional string` + + The ID of the file to be sent to the model. + + - `image_url: optional string` + + 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 }` + + A file input to the model. + + - `type: "input_file"` + + The type of the input item. Always `input_file`. + + - `"input_file"` + + - `detail: optional "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`. + + - `"low"` + + - `"high"` + + - `file_data: optional string` + + The base64-encoded data of the file to be sent to the model. + + - `file_id: optional string` + + The ID of the file to be sent to the model. + + - `file_url: optional string` + + The URL of the file to be sent to the model. + + - `filename: optional string` + + The name of the file to be sent to the model. + + - `type: "function_call_output"` + + The type of the function tool call output. Always `function_call_output`. + + - `"function_call_output"` + + - `id: optional string` + + The unique ID of the function tool call output. Populated when this item is returned via API. + + - `status: optional "in_progress" or "completed" or "incomplete"` + + The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `ToolSearchCall object { arguments, type, id, 3 more }` + + - `arguments: unknown` + + The arguments supplied to the tool search call. + + - `type: "tool_search_call"` + + The item type. Always `tool_search_call`. + + - `"tool_search_call"` + + - `id: optional string` + + The unique ID of this tool search call. + + - `call_id: optional string` + + The unique ID of the tool search call generated by the model. + + - `execution: optional "server" or "client"` + + Whether tool search was executed by the server or by the client. + + - `"server"` + + - `"client"` + + - `status: optional "in_progress" or "completed" or "incomplete"` + + The status of the tool search call. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `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` + + The loaded tool definitions returned by the tool search output. + + - `Function object { name, parameters, strict, 3 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). + + - `name: string` + + The name of the function to call. + + - `parameters: map[unknown]` + + A JSON schema object describing the parameters of the function. + + - `strict: boolean` + + Whether to enforce strict parameter validation. Default `true`. + + - `type: "function"` + + The type of the function tool. Always `function`. + + - `"function"` + + - `defer_loading: optional boolean` + + Whether this function is deferred and loaded via tool search. + + - `description: optional string` + + A description of the function. Used by the model to determine whether or not to call the function. + + - `FileSearch object { type, vector_store_ids, filters, 2 more }` + + A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). + + - `type: "file_search"` + + The type of the file search tool. Always `file_search`. + + - `"file_search"` + + - `vector_store_ids: array of string` + + The IDs of the vector stores to search. + + - `filters: optional ComparisonFilter or CompoundFilter` + + A filter to apply. + + - `ComparisonFilter object { key, type, value }` + + A filter used to compare a specified attribute key to a given value using a defined comparison operation. + + - `key: string` + + The key to compare against the value. + + - `type: "eq" or "ne" or "gt" or 5 more` + + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + + - `eq`: equals + - `ne`: not equal + - `gt`: greater than + - `gte`: greater than or equal + - `lt`: less than + - `lte`: less than or equal + - `in`: in + - `nin`: not in + + - `"eq"` + + - `"ne"` + + - `"gt"` + + - `"gte"` + + - `"lt"` + + - `"lte"` + + - `"in"` + + - `"nin"` + + - `value: string or number or boolean or array of string or number` + + The value to compare against the attribute key; supports string, number, or boolean types. + + - `string` + + - `number` + + - `boolean` + + - `array of string or number` + + - `string` + + - `number` + + - `CompoundFilter object { filters, type }` + + Combine multiple filters using `and` or `or`. + + - `filters: array of ComparisonFilter or unknown` + + Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. + + - `ComparisonFilter object { key, type, value }` + + A filter used to compare a specified attribute key to a given value using a defined comparison operation. + + - `unknown` + + - `type: "and" or "or"` + + Type of operation: `and` or `or`. + + - `"and"` + + - `"or"` + + - `max_num_results: optional number` + + The maximum number of results to return. This number should be between 1 and 50 inclusive. + + - `ranking_options: optional object { hybrid_search, ranker, score_threshold }` + + Ranking options for search. + + - `hybrid_search: optional object { embedding_weight, text_weight }` + + Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. + + - `embedding_weight: number` + + The weight of the embedding in the reciprocal ranking fusion. + + - `text_weight: number` + + The weight of the text in the reciprocal ranking fusion. + + - `ranker: optional "auto" or "default-2024-11-15"` + + The ranker to use for the file search. + + - `"auto"` + + - `"default-2024-11-15"` + + - `score_threshold: optional number` + + The score threshold for the file search, a number between 0 and 1. Numbers closer to 1 will attempt to return only the most relevant results, but may return fewer results. + + - `Computer object { type }` + + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + + - `type: "computer"` + + The type of the computer tool. Always `computer`. + + - `"computer"` + + - `ComputerUsePreview object { display_height, display_width, environment, type }` + + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + + - `display_height: number` + + The height of the computer display. + + - `display_width: number` + + The width of the computer display. + + - `environment: "windows" or "mac" or "linux" or 2 more` + + The type of computer environment to control. + + - `"windows"` + + - `"mac"` + + - `"linux"` + + - `"ubuntu"` + + - `"browser"` + + - `type: "computer_use_preview"` + + The type of the computer use tool. Always `computer_use_preview`. + + - `"computer_use_preview"` + + - `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). + + - `type: "web_search" or "web_search_2025_08_26"` + + The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. + + - `"web_search"` + + - `"web_search_2025_08_26"` + + - `filters: optional object { allowed_domains }` + + Filters for the search. + + - `allowed_domains: optional array of string` + + Allowed domains for the search. If not provided, all domains are allowed. + Subdomains of the provided domains are allowed as well. + + Example: `["pubmed.ncbi.nlm.nih.gov"]` + + - `search_context_size: optional "low" or "medium" or "high"` + + High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. + + - `"low"` + + - `"medium"` + + - `"high"` + + - `user_location: optional object { city, country, region, 2 more }` + + The approximate location of the user. + + - `city: optional string` + + Free text input for the city of the user, e.g. `San Francisco`. + + - `country: optional string` + + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + + - `region: optional string` + + Free text input for the region of the user, e.g. `California`. + + - `timezone: optional string` + + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + + - `type: optional "approximate"` + + The type of location approximation. Always `approximate`. + + - `"approximate"` + + - `Mcp object { server_label, type, allowed_tools, 7 more }` + + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](/docs/guides/tools-remote-mcp). + + - `server_label: string` + + A label for this MCP server, used to identify it in tool calls. + + - `type: "mcp"` + + The type of the MCP tool. Always `mcp`. + + - `"mcp"` + + - `allowed_tools: optional array of string or object { read_only, tool_names }` + + List of allowed tool names or a filter object. + + - `McpAllowedTools = array of string` + + A string array of allowed tool names + + - `McpToolFilter object { read_only, tool_names }` + + A filter object to specify which tools are allowed. + + - `read_only: optional boolean` + + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. + + - `tool_names: optional array of string` + + List of allowed tool names. + + - `authorization: optional string` + + An OAuth access token that can be used with a remote MCP server, either + with a custom MCP server URL or a service connector. Your application + must handle the OAuth authorization flow and provide the token here. + + - `connector_id: optional "connector_dropbox" or "connector_gmail" or "connector_googlecalendar" or 5 more` + + Identifier for service connectors, like those available in ChatGPT. One of + `server_url` or `connector_id` must be provided. Learn more about service + connectors [here](/docs/guides/tools-remote-mcp#connectors). + + Currently supported `connector_id` values are: + + - Dropbox: `connector_dropbox` + - Gmail: `connector_gmail` + - Google Calendar: `connector_googlecalendar` + - Google Drive: `connector_googledrive` + - Microsoft Teams: `connector_microsoftteams` + - Outlook Calendar: `connector_outlookcalendar` + - Outlook Email: `connector_outlookemail` + - SharePoint: `connector_sharepoint` + + - `"connector_dropbox"` + + - `"connector_gmail"` + + - `"connector_googlecalendar"` + + - `"connector_googledrive"` + + - `"connector_microsoftteams"` + + - `"connector_outlookcalendar"` + + - `"connector_outlookemail"` + + - `"connector_sharepoint"` + + - `defer_loading: optional boolean` + + Whether this MCP tool is deferred and discovered via tool search. + + - `headers: optional map[string]` + + Optional HTTP headers to send to the MCP server. Use for authentication + or other purposes. + + - `require_approval: optional object { always, never } or "always" or "never"` + + Specify which of the MCP server's tools require approval. + + - `McpToolApprovalFilter object { always, never }` + + Specify which of the MCP server's tools require approval. Can be + `always`, `never`, or a filter object associated with tools + that require approval. + + - `always: optional object { read_only, tool_names }` + + A filter object to specify which tools are allowed. + + - `read_only: optional boolean` + + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. + + - `tool_names: optional array of string` + + List of allowed tool names. + + - `never: optional object { read_only, tool_names }` + + A filter object to specify which tools are allowed. + + - `read_only: optional boolean` + + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. + + - `tool_names: optional array of string` + + List of allowed tool names. + + - `McpToolApprovalSetting = "always" or "never"` + + Specify a single approval policy for all tools. One of `always` or + `never`. When set to `always`, all tools will require approval. When + set to `never`, all tools will not require approval. + + - `"always"` + + - `"never"` + + - `server_description: optional string` + + Optional description of the MCP server, used to provide more context. + + - `server_url: optional string` + + The URL for the MCP server. One of `server_url` or `connector_id` must be + provided. + + - `CodeInterpreter object { container, type }` + + A tool that runs Python code to help generate a response to a prompt. + + - `container: string or object { type, file_ids, memory_limit, network_policy }` + + The code interpreter container. Can be a container ID or an object that + specifies uploaded file IDs to make available to your code, along with an + optional `memory_limit` setting. + + - `string` + + The container ID. + + - `CodeInterpreterToolAuto object { type, file_ids, memory_limit, network_policy }` + + Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. + + - `type: "auto"` + + Always `auto`. + + - `"auto"` + + - `file_ids: optional array of string` + + An optional list of uploaded files to make available to your code. + + - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` + + The memory limit for the code interpreter container. + + - `"1g"` + + - `"4g"` + + - `"16g"` + + - `"64g"` + + - `network_policy: optional ContainerNetworkPolicyDisabled or ContainerNetworkPolicyAllowlist` + + Network access policy for the container. + + - `ContainerNetworkPolicyDisabled object { type }` + + - `type: "disabled"` + + Disable outbound network access. Always `disabled`. + + - `"disabled"` + + - `ContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` + + - `allowed_domains: array of string` + + A list of allowed domains when type is `allowlist`. + + - `type: "allowlist"` + + Allow outbound network access only to specified domains. Always `allowlist`. + + - `"allowlist"` + + - `domain_secrets: optional array of ContainerNetworkPolicyDomainSecret` + + Optional domain-scoped secrets for allowlisted domains. + + - `domain: string` + + The domain associated with the secret. + + - `name: string` + + The name of the secret to inject for the domain. + + - `value: string` + + The secret value to inject for the domain. + + - `type: "code_interpreter"` + + The type of the code interpreter tool. Always `code_interpreter`. + + - `"code_interpreter"` + + - `ImageGeneration object { type, action, background, 9 more }` + + A tool that generates images using the GPT image models. + + - `type: "image_generation"` + + The type of the image generation tool. Always `image_generation`. + + - `"image_generation"` + + - `action: optional "generate" or "edit" or "auto"` + + Whether to generate a new image or edit an existing image. Default: `auto`. + + - `"generate"` + + - `"edit"` + + - `"auto"` + + - `background: optional "transparent" or "opaque" or "auto"` + + Background type for the generated image. One of `transparent`, + `opaque`, or `auto`. Default: `auto`. + + - `"transparent"` + + - `"opaque"` + + - `"auto"` + + - `input_fidelity: optional "high" or "low"` + + Control how much effort the model will exert to match the style and features, especially facial features, of input images. This parameter is only supported for `gpt-image-1` and `gpt-image-1.5` and later models, unsupported for `gpt-image-1-mini`. Supports `high` and `low`. Defaults to `low`. + + - `"high"` + + - `"low"` + + - `input_image_mask: optional object { file_id, image_url }` + + Optional mask for inpainting. Contains `image_url` + (string, optional) and `file_id` (string, optional). + + - `file_id: optional string` + + File ID for the mask image. + + - `image_url: optional string` + + Base64-encoded mask image. + + - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` + + The image generation model to use. Default: `gpt-image-1`. + + - `string` + + - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` + + The image generation model to use. Default: `gpt-image-1`. + + - `"gpt-image-1"` + + - `"gpt-image-1-mini"` + + - `"gpt-image-1.5"` + + - `moderation: optional "auto" or "low"` + + Moderation level for the generated image. Default: `auto`. + + - `"auto"` + + - `"low"` + + - `output_compression: optional number` + + Compression level for the output image. Default: 100. + + - `output_format: optional "png" or "webp" or "jpeg"` + + The output format of the generated image. One of `png`, `webp`, or + `jpeg`. Default: `png`. + + - `"png"` + + - `"webp"` + + - `"jpeg"` + + - `partial_images: optional number` + + Number of partial images to generate in streaming mode, from 0 (default value) to 3. + + - `quality: optional "low" or "medium" or "high" or "auto"` + + The quality of the generated image. One of `low`, `medium`, `high`, + or `auto`. Default: `auto`. + + - `"low"` + + - `"medium"` + + - `"high"` + + - `"auto"` + + - `size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or "auto"` + + The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. + + - `string` + + - `"1024x1024" or "1024x1536" or "1536x1024" or "auto"` + + The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. + + - `"1024x1024"` + + - `"1024x1536"` + + - `"1536x1024"` + + - `"auto"` + + - `LocalShell object { type }` + + A tool that allows the model to execute shell commands in a local environment. + + - `type: "local_shell"` + + The type of the local shell tool. Always `local_shell`. + + - `"local_shell"` + + - `Shell object { type, environment }` + + A tool that allows the model to execute shell commands. + + - `type: "shell"` + + The type of the shell tool. Always `shell`. + + - `"shell"` + + - `environment: optional ContainerAuto or LocalEnvironment or ContainerReference` + + - `ContainerAuto object { type, file_ids, memory_limit, 2 more }` + + - `type: "container_auto"` + + Automatically creates a container for this request + + - `"container_auto"` + + - `file_ids: optional array of string` + + An optional list of uploaded files to make available to your code. + + - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` + + The memory limit for the container. + + - `"1g"` + + - `"4g"` + + - `"16g"` + + - `"64g"` + + - `network_policy: optional ContainerNetworkPolicyDisabled or ContainerNetworkPolicyAllowlist` + + Network access policy for the container. + + - `ContainerNetworkPolicyDisabled object { type }` + + - `ContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` + + - `skills: optional array of SkillReference or InlineSkill` + + An optional list of skills referenced by id or inline data. + + - `SkillReference object { skill_id, type, version }` + + - `skill_id: string` + + The ID of the referenced skill. + + - `type: "skill_reference"` + + References a skill created with the /v1/skills endpoint. + + - `"skill_reference"` + + - `version: optional string` + + Optional skill version. Use a positive integer or 'latest'. Omit for default. + + - `InlineSkill object { description, name, source, type }` + + - `description: string` + + The description of the skill. + + - `name: string` + + The name of the skill. + + - `source: InlineSkillSource` + + Inline skill payload + + - `data: string` + + Base64-encoded skill zip bundle. + + - `media_type: "application/zip"` + + The media type of the inline skill payload. Must be `application/zip`. + + - `"application/zip"` + + - `type: "base64"` + + The type of the inline skill source. Must be `base64`. + + - `"base64"` + + - `type: "inline"` + + Defines an inline skill for this request. + + - `"inline"` + + - `LocalEnvironment object { type, skills }` + + - `type: "local"` + + Use a local computer environment. + + - `"local"` + + - `skills: optional array of LocalSkill` + + An optional list of skills. + + - `description: string` + + The description of the skill. + + - `name: string` + + The name of the skill. + + - `path: string` + + The path to the directory containing the skill. + + - `ContainerReference object { container_id, type }` + + - `container_id: string` + + The ID of the referenced container. + + - `type: "container_reference"` + + References a container created with the /v1/containers endpoint + + - `"container_reference"` + + - `Custom object { name, type, defer_loading, 2 more }` + + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) + + - `name: string` + + The name of the custom tool, used to identify it in tool calls. + + - `type: "custom"` + + The type of the custom tool. Always `custom`. + + - `"custom"` + + - `defer_loading: optional boolean` + + Whether this tool should be deferred and discovered via tool search. + + - `description: optional string` + + Optional description of the custom tool, used to provide more context. + + - `format: optional CustomToolInputFormat` + + The input format for the custom tool. Default is unconstrained text. + + - `Text object { type }` + + Unconstrained free-form text. + + - `type: "text"` + + Unconstrained text format. Always `text`. + + - `"text"` + + - `Grammar object { definition, syntax, type }` + + A grammar defined by the user. + + - `definition: string` + + The grammar definition. + + - `syntax: "lark" or "regex"` + + The syntax of the grammar definition. One of `lark` or `regex`. + + - `"lark"` + + - `"regex"` + + - `type: "grammar"` + + Grammar format. Always `grammar`. + + - `"grammar"` + + - `Namespace object { description, name, tools, type }` + + Groups function/custom tools under a shared namespace. + + - `description: string` + + A description of the namespace shown to the model. + + - `name: string` + + The 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 }` + + The function/custom tools available inside this namespace. + + - `Function object { name, type, defer_loading, 3 more }` + + - `name: string` + + - `type: "function"` + + - `"function"` + + - `defer_loading: optional boolean` + + Whether this function should be deferred and discovered via tool search. + + - `description: optional string` + + - `parameters: optional unknown` + + - `strict: optional boolean` + + - `Custom object { name, type, defer_loading, 2 more }` + + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) + + - `name: string` + + The name of the custom tool, used to identify it in tool calls. + + - `type: "custom"` + + The type of the custom tool. Always `custom`. + + - `"custom"` + + - `defer_loading: optional boolean` + + Whether this tool should be deferred and discovered via tool search. + + - `description: optional string` + + Optional description of the custom tool, used to provide more context. + + - `format: optional CustomToolInputFormat` + + The input format for the custom tool. Default is unconstrained text. + + - `type: "namespace"` + + The type of the tool. Always `namespace`. + + - `"namespace"` + + - `ToolSearch object { type, description, execution, parameters }` + + Hosted or BYOT tool search configuration for deferred tools. + + - `type: "tool_search"` + + The type of the tool. Always `tool_search`. + + - `"tool_search"` + + - `description: optional string` + + Description shown to the model for a client-executed tool search tool. + + - `execution: optional "server" or "client"` + + Whether tool search is executed by the server or by the client. + + - `"server"` + + - `"client"` + + - `parameters: optional unknown` + + Parameter schema for a client-executed tool search tool. + + - `WebSearchPreview object { type, search_content_types, search_context_size, user_location }` + + This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + + - `type: "web_search_preview" or "web_search_preview_2025_03_11"` + + The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. + + - `"web_search_preview"` + + - `"web_search_preview_2025_03_11"` + + - `search_content_types: optional array of "text" or "image"` + + - `"text"` + + - `"image"` + + - `search_context_size: optional "low" or "medium" or "high"` + + High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. + + - `"low"` + + - `"medium"` + + - `"high"` + + - `user_location: optional object { type, city, country, 2 more }` + + The user's location. + + - `type: "approximate"` + + The type of location approximation. Always `approximate`. + + - `"approximate"` + + - `city: optional string` + + Free text input for the city of the user, e.g. `San Francisco`. + + - `country: optional string` + + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + + - `region: optional string` + + Free text input for the region of the user, e.g. `California`. + + - `timezone: optional string` + + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + + - `ApplyPatch object { type }` + + Allows the assistant to create, delete, or update files using unified diffs. + + - `type: "apply_patch"` + + The type of the tool. Always `apply_patch`. + + - `"apply_patch"` + + - `type: "tool_search_output"` + + The item type. Always `tool_search_output`. + + - `"tool_search_output"` + + - `id: optional string` + + The unique ID of this tool search output. + + - `call_id: optional string` + + The unique ID of the tool search call generated by the model. + + - `execution: optional "server" or "client"` + + Whether tool search was executed by the server or by the client. + + - `"server"` + + - `"client"` + + - `status: optional "in_progress" or "completed" or "incomplete"` + + The status of the tool search output. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `AdditionalTools object { role, tools, type, id }` + + - `role: "developer"` + + The role that provided the additional tools. Only `developer` is supported. + + - `"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` + + A list of additional tools made available at this item. + + - `Function object { name, parameters, strict, 3 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). + + - `name: string` + + The name of the function to call. + + - `parameters: map[unknown]` + + A JSON schema object describing the parameters of the function. + + - `strict: boolean` + + Whether to enforce strict parameter validation. Default `true`. + + - `type: "function"` + + The type of the function tool. Always `function`. + + - `"function"` + + - `defer_loading: optional boolean` + + Whether this function is deferred and loaded via tool search. + + - `description: optional string` + + A description of the function. Used by the model to determine whether or not to call the function. + + - `FileSearch object { type, vector_store_ids, filters, 2 more }` + + A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). + + - `type: "file_search"` + + The type of the file search tool. Always `file_search`. + + - `"file_search"` + + - `vector_store_ids: array of string` + + The IDs of the vector stores to search. + + - `filters: optional ComparisonFilter or CompoundFilter` + + A filter to apply. + + - `ComparisonFilter object { key, type, value }` + + A filter used to compare a specified attribute key to a given value using a defined comparison operation. + + - `CompoundFilter object { filters, type }` + + Combine multiple filters using `and` or `or`. + + - `max_num_results: optional number` + + The maximum number of results to return. This number should be between 1 and 50 inclusive. + + - `ranking_options: optional object { hybrid_search, ranker, score_threshold }` + + Ranking options for search. + + - `hybrid_search: optional object { embedding_weight, text_weight }` + + Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. + + - `embedding_weight: number` + + The weight of the embedding in the reciprocal ranking fusion. + + - `text_weight: number` + + The weight of the text in the reciprocal ranking fusion. + + - `ranker: optional "auto" or "default-2024-11-15"` + + The ranker to use for the file search. + + - `"auto"` + + - `"default-2024-11-15"` + + - `score_threshold: optional number` + + The score threshold for the file search, a number between 0 and 1. Numbers closer to 1 will attempt to return only the most relevant results, but may return fewer results. + + - `Computer object { type }` + + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + + - `type: "computer"` + + The type of the computer tool. Always `computer`. + + - `"computer"` + + - `ComputerUsePreview object { display_height, display_width, environment, type }` + + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + + - `display_height: number` + + The height of the computer display. + + - `display_width: number` + + The width of the computer display. + + - `environment: "windows" or "mac" or "linux" or 2 more` + + The type of computer environment to control. + + - `"windows"` + + - `"mac"` + + - `"linux"` + + - `"ubuntu"` + + - `"browser"` + + - `type: "computer_use_preview"` + + The type of the computer use tool. Always `computer_use_preview`. + + - `"computer_use_preview"` + + - `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). + + - `type: "web_search" or "web_search_2025_08_26"` + + The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. + + - `"web_search"` + + - `"web_search_2025_08_26"` + + - `filters: optional object { allowed_domains }` + + Filters for the search. + + - `allowed_domains: optional array of string` + + Allowed domains for the search. If not provided, all domains are allowed. + Subdomains of the provided domains are allowed as well. + + Example: `["pubmed.ncbi.nlm.nih.gov"]` + + - `search_context_size: optional "low" or "medium" or "high"` + + High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. + + - `"low"` + + - `"medium"` + + - `"high"` + + - `user_location: optional object { city, country, region, 2 more }` + + The approximate location of the user. + + - `city: optional string` + + Free text input for the city of the user, e.g. `San Francisco`. + + - `country: optional string` + + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + + - `region: optional string` + + Free text input for the region of the user, e.g. `California`. + + - `timezone: optional string` + + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + + - `type: optional "approximate"` + + The type of location approximation. Always `approximate`. + + - `"approximate"` + + - `Mcp object { server_label, type, allowed_tools, 7 more }` + + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](/docs/guides/tools-remote-mcp). + + - `server_label: string` + + A label for this MCP server, used to identify it in tool calls. + + - `type: "mcp"` + + The type of the MCP tool. Always `mcp`. + + - `"mcp"` + + - `allowed_tools: optional array of string or object { read_only, tool_names }` + + List of allowed tool names or a filter object. + + - `McpAllowedTools = array of string` + + A string array of allowed tool names + + - `McpToolFilter object { read_only, tool_names }` + + A filter object to specify which tools are allowed. + + - `read_only: optional boolean` + + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. + + - `tool_names: optional array of string` + + List of allowed tool names. + + - `authorization: optional string` + + An OAuth access token that can be used with a remote MCP server, either + with a custom MCP server URL or a service connector. Your application + must handle the OAuth authorization flow and provide the token here. + + - `connector_id: optional "connector_dropbox" or "connector_gmail" or "connector_googlecalendar" or 5 more` + + Identifier for service connectors, like those available in ChatGPT. One of + `server_url` or `connector_id` must be provided. Learn more about service + connectors [here](/docs/guides/tools-remote-mcp#connectors). + + Currently supported `connector_id` values are: + + - Dropbox: `connector_dropbox` + - Gmail: `connector_gmail` + - Google Calendar: `connector_googlecalendar` + - Google Drive: `connector_googledrive` + - Microsoft Teams: `connector_microsoftteams` + - Outlook Calendar: `connector_outlookcalendar` + - Outlook Email: `connector_outlookemail` + - SharePoint: `connector_sharepoint` + + - `"connector_dropbox"` + + - `"connector_gmail"` + + - `"connector_googlecalendar"` + + - `"connector_googledrive"` + + - `"connector_microsoftteams"` + + - `"connector_outlookcalendar"` + + - `"connector_outlookemail"` + + - `"connector_sharepoint"` + + - `defer_loading: optional boolean` + + Whether this MCP tool is deferred and discovered via tool search. + + - `headers: optional map[string]` + + Optional HTTP headers to send to the MCP server. Use for authentication + or other purposes. + + - `require_approval: optional object { always, never } or "always" or "never"` + + Specify which of the MCP server's tools require approval. + + - `McpToolApprovalFilter object { always, never }` + + Specify which of the MCP server's tools require approval. Can be + `always`, `never`, or a filter object associated with tools + that require approval. + + - `always: optional object { read_only, tool_names }` + + A filter object to specify which tools are allowed. + + - `read_only: optional boolean` + + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. + + - `tool_names: optional array of string` + + List of allowed tool names. + + - `never: optional object { read_only, tool_names }` + + A filter object to specify which tools are allowed. + + - `read_only: optional boolean` + + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. + + - `tool_names: optional array of string` + + List of allowed tool names. + + - `McpToolApprovalSetting = "always" or "never"` + + Specify a single approval policy for all tools. One of `always` or + `never`. When set to `always`, all tools will require approval. When + set to `never`, all tools will not require approval. + + - `"always"` + + - `"never"` + + - `server_description: optional string` + + Optional description of the MCP server, used to provide more context. + + - `server_url: optional string` + + The URL for the MCP server. One of `server_url` or `connector_id` must be + provided. + + - `CodeInterpreter object { container, type }` + + A tool that runs Python code to help generate a response to a prompt. + + - `container: string or object { type, file_ids, memory_limit, network_policy }` + + The code interpreter container. Can be a container ID or an object that + specifies uploaded file IDs to make available to your code, along with an + optional `memory_limit` setting. + + - `string` + + The container ID. + + - `CodeInterpreterToolAuto object { type, file_ids, memory_limit, network_policy }` + + Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. + + - `type: "auto"` + + Always `auto`. + + - `"auto"` + + - `file_ids: optional array of string` + + An optional list of uploaded files to make available to your code. + + - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` + + The memory limit for the code interpreter container. + + - `"1g"` + + - `"4g"` + + - `"16g"` + + - `"64g"` + + - `network_policy: optional ContainerNetworkPolicyDisabled or ContainerNetworkPolicyAllowlist` + + Network access policy for the container. + + - `ContainerNetworkPolicyDisabled object { type }` + + - `ContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` + + - `type: "code_interpreter"` + + The type of the code interpreter tool. Always `code_interpreter`. + + - `"code_interpreter"` + + - `ImageGeneration object { type, action, background, 9 more }` + + A tool that generates images using the GPT image models. + + - `type: "image_generation"` + + The type of the image generation tool. Always `image_generation`. + + - `"image_generation"` + + - `action: optional "generate" or "edit" or "auto"` + + Whether to generate a new image or edit an existing image. Default: `auto`. + + - `"generate"` + + - `"edit"` + + - `"auto"` + + - `background: optional "transparent" or "opaque" or "auto"` + + Background type for the generated image. One of `transparent`, + `opaque`, or `auto`. Default: `auto`. + + - `"transparent"` + + - `"opaque"` + + - `"auto"` + + - `input_fidelity: optional "high" or "low"` + + Control how much effort the model will exert to match the style and features, especially facial features, of input images. This parameter is only supported for `gpt-image-1` and `gpt-image-1.5` and later models, unsupported for `gpt-image-1-mini`. Supports `high` and `low`. Defaults to `low`. + + - `"high"` + + - `"low"` + + - `input_image_mask: optional object { file_id, image_url }` + + Optional mask for inpainting. Contains `image_url` + (string, optional) and `file_id` (string, optional). + + - `file_id: optional string` + + File ID for the mask image. + + - `image_url: optional string` + + Base64-encoded mask image. + + - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` + + The image generation model to use. Default: `gpt-image-1`. + + - `string` + + - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` + + The image generation model to use. Default: `gpt-image-1`. + + - `"gpt-image-1"` + + - `"gpt-image-1-mini"` + + - `"gpt-image-1.5"` + + - `moderation: optional "auto" or "low"` + + Moderation level for the generated image. Default: `auto`. + + - `"auto"` + + - `"low"` + + - `output_compression: optional number` + + Compression level for the output image. Default: 100. + + - `output_format: optional "png" or "webp" or "jpeg"` + + The output format of the generated image. One of `png`, `webp`, or + `jpeg`. Default: `png`. + + - `"png"` + + - `"webp"` + + - `"jpeg"` + + - `partial_images: optional number` + + Number of partial images to generate in streaming mode, from 0 (default value) to 3. + + - `quality: optional "low" or "medium" or "high" or "auto"` + + The quality of the generated image. One of `low`, `medium`, `high`, + or `auto`. Default: `auto`. + + - `"low"` + + - `"medium"` + + - `"high"` + + - `"auto"` + + - `size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or "auto"` + + The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. + + - `string` + + - `"1024x1024" or "1024x1536" or "1536x1024" or "auto"` + + The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. + + - `"1024x1024"` + + - `"1024x1536"` + + - `"1536x1024"` + + - `"auto"` + + - `LocalShell object { type }` + + A tool that allows the model to execute shell commands in a local environment. + + - `type: "local_shell"` + + The type of the local shell tool. Always `local_shell`. + + - `"local_shell"` + + - `Shell object { type, environment }` + + A tool that allows the model to execute shell commands. + + - `type: "shell"` + + The type of the shell tool. Always `shell`. + + - `"shell"` + + - `environment: optional ContainerAuto or LocalEnvironment or ContainerReference` + + - `ContainerAuto object { type, file_ids, memory_limit, 2 more }` + + - `LocalEnvironment object { type, skills }` + + - `ContainerReference object { container_id, type }` + + - `Custom object { name, type, defer_loading, 2 more }` + + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) + + - `name: string` + + The name of the custom tool, used to identify it in tool calls. + + - `type: "custom"` + + The type of the custom tool. Always `custom`. + + - `"custom"` + + - `defer_loading: optional boolean` + + Whether this tool should be deferred and discovered via tool search. + + - `description: optional string` + + Optional description of the custom tool, used to provide more context. + + - `format: optional CustomToolInputFormat` + + The input format for the custom tool. Default is unconstrained text. + + - `Namespace object { description, name, tools, type }` + + Groups function/custom tools under a shared namespace. + + - `description: string` + + A description of the namespace shown to the model. + + - `name: string` + + The 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 }` + + The function/custom tools available inside this namespace. + + - `Function object { name, type, defer_loading, 3 more }` + + - `name: string` + + - `type: "function"` + + - `"function"` + + - `defer_loading: optional boolean` + + Whether this function should be deferred and discovered via tool search. + + - `description: optional string` + + - `parameters: optional unknown` + + - `strict: optional boolean` + + - `Custom object { name, type, defer_loading, 2 more }` + + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) + + - `name: string` + + The name of the custom tool, used to identify it in tool calls. + + - `type: "custom"` + + The type of the custom tool. Always `custom`. + + - `"custom"` + + - `defer_loading: optional boolean` + + Whether this tool should be deferred and discovered via tool search. + + - `description: optional string` + + Optional description of the custom tool, used to provide more context. + + - `format: optional CustomToolInputFormat` + + The input format for the custom tool. Default is unconstrained text. + + - `type: "namespace"` + + The type of the tool. Always `namespace`. + + - `"namespace"` + + - `ToolSearch object { type, description, execution, parameters }` + + Hosted or BYOT tool search configuration for deferred tools. + + - `type: "tool_search"` + + The type of the tool. Always `tool_search`. + + - `"tool_search"` + + - `description: optional string` + + Description shown to the model for a client-executed tool search tool. + + - `execution: optional "server" or "client"` + + Whether tool search is executed by the server or by the client. + + - `"server"` + + - `"client"` + + - `parameters: optional unknown` + + Parameter schema for a client-executed tool search tool. + + - `WebSearchPreview object { type, search_content_types, search_context_size, user_location }` + + This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + + - `type: "web_search_preview" or "web_search_preview_2025_03_11"` + + The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. + + - `"web_search_preview"` + + - `"web_search_preview_2025_03_11"` + + - `search_content_types: optional array of "text" or "image"` + + - `"text"` + + - `"image"` + + - `search_context_size: optional "low" or "medium" or "high"` + + High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. + + - `"low"` + + - `"medium"` + + - `"high"` + + - `user_location: optional object { type, city, country, 2 more }` + + The user's location. + + - `type: "approximate"` + + The type of location approximation. Always `approximate`. + + - `"approximate"` + + - `city: optional string` + + Free text input for the city of the user, e.g. `San Francisco`. + + - `country: optional string` + + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + + - `region: optional string` + + Free text input for the region of the user, e.g. `California`. + + - `timezone: optional string` + + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + + - `ApplyPatch object { type }` + + Allows the assistant to create, delete, or update files using unified diffs. + + - `type: "apply_patch"` + + The type of the tool. Always `apply_patch`. + + - `"apply_patch"` + + - `type: "additional_tools"` + + The item type. Always `additional_tools`. + + - `"additional_tools"` + + - `id: optional string` + + The unique ID of this additional tools item. + + - `Reasoning object { id, summary, type, 3 more }` + + 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). + + - `id: string` + + The unique identifier of the reasoning content. + + - `summary: array of SummaryTextContent` + + Reasoning summary content. + + - `text: string` + + A summary of the reasoning output from the model so far. + + - `type: "summary_text"` + + The type of the object. Always `summary_text`. + + - `"summary_text"` + + - `type: "reasoning"` + + The type of the object. Always `reasoning`. + + - `"reasoning"` + + - `content: optional array of object { text, type }` + + Reasoning text content. + + - `text: string` + + The reasoning text from the model. + + - `type: "reasoning_text"` + + The type of the reasoning text. Always `reasoning_text`. + + - `"reasoning_text"` + + - `encrypted_content: optional string` + + The encrypted content of the reasoning item - populated when a response is + generated with `reasoning.encrypted_content` in the `include` parameter. + + - `status: optional "in_progress" or "completed" or "incomplete"` + + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `Compaction object { encrypted_content, type, id }` + + A compaction item generated by the [`v1/responses/compact` API](/docs/api-reference/responses/compact). + + - `encrypted_content: string` + + The encrypted content of the compaction summary. + + - `type: "compaction"` + + The type of the item. Always `compaction`. + + - `"compaction"` + + - `id: optional string` + + The ID of the compaction item. + + - `ImageGenerationCall object { id, result, status, type }` + + An image generation request made by the model. + + - `id: string` + + The unique ID of the image generation call. + + - `result: string` + + The generated image encoded in base64. + + - `status: "in_progress" or "completed" or "generating" or "failed"` + + The status of the image generation call. + + - `"in_progress"` + + - `"completed"` + + - `"generating"` + + - `"failed"` + + - `type: "image_generation_call"` + + The type of the image generation call. Always `image_generation_call`. + + - `"image_generation_call"` + + - `CodeInterpreterCall object { id, code, container_id, 3 more }` + + A tool call to run code. + + - `id: string` + + The unique ID of the code interpreter tool call. + + - `code: string` + + The code to run, or null if not available. + + - `container_id: string` + + The ID of the container used to run the code. + + - `outputs: array of object { logs, type } or object { type, url }` + + The outputs generated by the code interpreter, such as logs or images. + Can be null if no outputs are available. + + - `Logs object { logs, type }` + + The logs output from the code interpreter. + + - `logs: string` + + The logs output from the code interpreter. + + - `type: "logs"` + + The type of the output. Always `logs`. + + - `"logs"` + + - `Image object { type, url }` + + The image output from the code interpreter. + + - `type: "image"` + + The type of the output. Always `image`. + + - `"image"` + + - `url: string` + + The URL of the image output from the code interpreter. + + - `status: "in_progress" or "completed" or "incomplete" or 2 more` + + The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `"interpreting"` + + - `"failed"` + + - `type: "code_interpreter_call"` + + The type of the code interpreter tool call. Always `code_interpreter_call`. + + - `"code_interpreter_call"` + + - `LocalShellCall object { id, action, call_id, 2 more }` + + A tool call to run a command on the local shell. + + - `id: string` + + The unique ID of the local shell call. + + - `action: object { command, env, type, 3 more }` + + Execute a shell command on the server. + + - `command: array of string` + + The command to run. + + - `env: map[string]` + + Environment variables to set for the command. + + - `type: "exec"` + + The type of the local shell action. Always `exec`. + + - `"exec"` + + - `timeout_ms: optional number` + + Optional timeout in milliseconds for the command. + + - `user: optional string` + + Optional user to run the command as. + + - `working_directory: optional string` + + Optional working directory to run the command in. + + - `call_id: string` + + The unique ID of the local shell tool call generated by the model. + + - `status: "in_progress" or "completed" or "incomplete"` + + The status of the local shell call. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `type: "local_shell_call"` + + The type of the local shell call. Always `local_shell_call`. + + - `"local_shell_call"` + + - `LocalShellCallOutput object { id, output, type, status }` + + The output of a local shell tool call. + + - `id: string` + + The unique ID of the local shell tool call generated by the model. + + - `output: string` + + A JSON string of the output of the local shell tool call. + + - `type: "local_shell_call_output"` + + The type of the local shell tool call output. Always `local_shell_call_output`. + + - `"local_shell_call_output"` + + - `status: optional "in_progress" or "completed" or "incomplete"` + + The status of the item. One of `in_progress`, `completed`, or `incomplete`. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `ShellCall object { action, call_id, type, 3 more }` + + A tool representing a request to execute one or more shell commands. + + - `action: object { commands, max_output_length, timeout_ms }` + + The shell commands and limits that describe how to run the tool call. + + - `commands: array of string` + + Ordered shell commands for the execution environment to run. + + - `max_output_length: optional number` + + Maximum number of UTF-8 characters to capture from combined stdout and stderr output. + + - `timeout_ms: optional number` + + Maximum wall-clock time in milliseconds to allow the shell commands to run. + + - `call_id: string` + + The unique ID of the shell tool call generated by the model. + + - `type: "shell_call"` + + The type of the item. Always `shell_call`. + + - `"shell_call"` + + - `id: optional string` + + The unique ID of the shell tool call. Populated when this item is returned via API. + + - `environment: optional LocalEnvironment or ContainerReference` + + The environment to execute the shell commands in. + + - `LocalEnvironment object { type, skills }` + + - `ContainerReference object { container_id, type }` + + - `status: optional "in_progress" or "completed" or "incomplete"` + + The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `ShellCallOutput object { call_id, output, type, 3 more }` + + The streamed output items emitted by a shell tool call. + + - `call_id: string` + + The unique ID of the shell tool call generated by the model. + + - `output: array of ResponseFunctionShellCallOutputContent` + + Captured chunks of stdout and stderr output, along with their associated outcomes. + + - `outcome: object { type } or object { exit_code, type }` + + The exit or timeout outcome associated with this shell call. + + - `Timeout object { type }` + + Indicates that the shell call exceeded its configured time limit. + + - `type: "timeout"` + + The outcome type. Always `timeout`. + + - `"timeout"` + + - `Exit object { exit_code, type }` + + Indicates that the shell commands finished and returned an exit code. + + - `exit_code: number` + + The exit code returned by the shell process. + + - `type: "exit"` + + The outcome type. Always `exit`. + + - `"exit"` + + - `stderr: string` + + Captured stderr output for the shell call. + + - `stdout: string` + + Captured stdout output for the shell call. + + - `type: "shell_call_output"` + + The type of the item. Always `shell_call_output`. + + - `"shell_call_output"` + + - `id: optional string` + + The unique ID of the shell tool call output. Populated when this item is returned via API. + + - `max_output_length: optional number` + + The maximum number of UTF-8 characters captured for this shell call's combined output. + + - `status: optional "in_progress" or "completed" or "incomplete"` + + The status of the shell call output. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `ApplyPatchCall object { call_id, operation, status, 2 more }` + + A tool call representing a request to create, delete, or update files using diff patches. + + - `call_id: string` + + The unique ID of the apply patch tool call generated by the model. + + - `operation: object { diff, path, type } or object { path, type } or object { diff, path, type }` + + The specific create, delete, or update instruction for the apply_patch tool call. + + - `CreateFile object { diff, path, type }` + + Instruction for creating a new file via the apply_patch tool. + + - `diff: string` + + Unified diff content to apply when creating the file. + + - `path: string` + + Path of the file to create relative to the workspace root. + + - `type: "create_file"` + + The operation type. Always `create_file`. + + - `"create_file"` + + - `DeleteFile object { path, type }` + + Instruction for deleting an existing file via the apply_patch tool. + + - `path: string` + + Path of the file to delete relative to the workspace root. + + - `type: "delete_file"` + + The operation type. Always `delete_file`. + + - `"delete_file"` + + - `UpdateFile object { diff, path, type }` + + Instruction for updating an existing file via the apply_patch tool. + + - `diff: string` + + Unified diff content to apply to the existing file. + + - `path: string` + + Path of the file to update relative to the workspace root. + + - `type: "update_file"` + + The operation type. Always `update_file`. + + - `"update_file"` + + - `status: "in_progress" or "completed"` + + The status of the apply patch tool call. One of `in_progress` or `completed`. + + - `"in_progress"` + + - `"completed"` + + - `type: "apply_patch_call"` + + The type of the item. Always `apply_patch_call`. + + - `"apply_patch_call"` + + - `id: optional string` + + 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 }` + + The streamed output emitted by an apply patch tool call. + + - `call_id: string` + + The unique ID of the apply patch tool call generated by the model. + + - `status: "completed" or "failed"` + + The status of the apply patch tool call output. One of `completed` or `failed`. + + - `"completed"` + + - `"failed"` + + - `type: "apply_patch_call_output"` + + The type of the item. Always `apply_patch_call_output`. + + - `"apply_patch_call_output"` + + - `id: optional string` + + The unique ID of the apply patch tool call output. Populated when this item is returned via API. + + - `output: optional string` + + Optional human-readable log text from the apply patch tool (e.g., patch results or errors). + + - `McpListTools object { id, server_label, tools, 2 more }` + + A list of tools available on an MCP server. + + - `id: string` + + The unique ID of the list. + + - `server_label: string` + + The label of the MCP server. + + - `tools: array of object { input_schema, name, annotations, description }` + + The tools available on the server. + + - `input_schema: unknown` + + The JSON schema describing the tool's input. + + - `name: string` + + The name of the tool. + + - `annotations: optional unknown` + + Additional annotations about the tool. + + - `description: optional string` + + The description of the tool. + + - `type: "mcp_list_tools"` + + The type of the item. Always `mcp_list_tools`. + + - `"mcp_list_tools"` + + - `error: optional string` + + Error message if the server could not list tools. + + - `McpApprovalRequest object { id, arguments, name, 2 more }` + + A request for human approval of a tool invocation. + + - `id: string` + + The unique ID of the approval request. + + - `arguments: string` + + A JSON string of arguments for the tool. + + - `name: string` + + The name of the tool to run. + + - `server_label: string` + + The label of the MCP server making the request. + + - `type: "mcp_approval_request"` + + The type of the item. Always `mcp_approval_request`. + + - `"mcp_approval_request"` + + - `McpApprovalResponse object { approval_request_id, approve, type, 2 more }` + + A response to an MCP approval request. + + - `approval_request_id: string` + + The ID of the approval request being answered. + + - `approve: boolean` + + Whether the request was approved. + + - `type: "mcp_approval_response"` + + The type of the item. Always `mcp_approval_response`. + + - `"mcp_approval_response"` + + - `id: optional string` + + The unique ID of the approval response + + - `reason: optional string` + + Optional reason for the decision. + + - `McpCall object { id, arguments, name, 6 more }` + + An invocation of a tool on an MCP server. + + - `id: string` + + The unique ID of the tool call. + + - `arguments: string` + + A JSON string of the arguments passed to the tool. + + - `name: string` + + The name of the tool that was run. + + - `server_label: string` + + The label of the MCP server running the tool. + + - `type: "mcp_call"` + + The type of the item. Always `mcp_call`. + + - `"mcp_call"` + + - `approval_request_id: optional string` + + Unique identifier for the MCP tool call approval request. + Include this value in a subsequent `mcp_approval_response` input to approve or reject the corresponding tool call. + + - `error: optional string` + + The error from the tool call, if any. + + - `output: optional string` + + The output from the tool call. + + - `status: optional "in_progress" or "completed" or "incomplete" or 2 more` + + The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `"calling"` + + - `"failed"` + + - `CustomToolCallOutput object { call_id, output, type, id }` + + The output of a custom tool call from your code, being sent back to the model. + + - `call_id: string` + + The call ID, used to map this custom tool call output to a custom tool call. + + - `output: string or array of ResponseInputText or ResponseInputImage or ResponseInputFile` + + The output from the custom tool call generated by your code. + Can be a string or an list of output content. + + - `StringOutput = string` + + A string of the output of the custom tool call. + + - `OutputContentList = array of ResponseInputText or ResponseInputImage or ResponseInputFile` + + Text, image, or file output of the custom tool call. + + - `ResponseInputText object { text, type }` + + A text input to the model. + + - `ResponseInputImage object { detail, type, file_id, image_url }` + + An image input to the model. Learn about [image inputs](/docs/guides/vision). + + - `ResponseInputFile object { type, detail, file_data, 3 more }` + + A file input to the model. + + - `type: "custom_tool_call_output"` + + The type of the custom tool call output. Always `custom_tool_call_output`. + + - `"custom_tool_call_output"` + + - `id: optional string` + + The unique ID of the custom tool call output in the OpenAI platform. + + - `CustomToolCall object { call_id, input, name, 3 more }` + + A call to a custom tool created by the model. + + - `call_id: string` + + An identifier used to map this custom tool call to a tool call output. + + - `input: string` + + The input for the custom tool call generated by the model. + + - `name: string` + + The name of the custom tool being called. + + - `type: "custom_tool_call"` + + The type of the custom tool call. Always `custom_tool_call`. + + - `"custom_tool_call"` + + - `id: optional string` + + The unique ID of the custom tool call in the OpenAI platform. + + - `namespace: optional string` + + The namespace of the custom tool being called. + + - `CompactionTrigger object { type }` + + Compacts the current context. Must be the final input item. + + - `type: "compaction_trigger"` + + The type of the item. Always `compaction_trigger`. + + - `"compaction_trigger"` + + - `ItemReference object { id, type }` + + An internal identifier for an item to reference. + + - `id: string` + + The ID of the item to reference. + + - `type: optional "item_reference"` + + The type of item to reference. Always `item_reference`. + + - `"item_reference"` + +### Returns + +- `ConversationItemList object { data, first_id, has_more, 2 more }` + + A list of Conversation items. + + - `data: array of ConversationItem` + + A list of conversation items. + + - `Message object { id, content, role, 3 more }` + + A message to or from the model. + + - `id: string` + + The unique ID of the message. + + - `content: array of ResponseInputText or ResponseOutputText or TextContent or 6 more` + + The content of the message + + - `ResponseInputText object { text, type }` + + A text input to the model. + + - `text: string` + + The text input to the model. + + - `type: "input_text"` + + The type of the input item. Always `input_text`. + + - `"input_text"` + + - `ResponseOutputText object { annotations, logprobs, text, type }` + + A text output from the model. + + - `annotations: array of object { file_id, filename, index, type } or object { end_index, start_index, title, 2 more } or object { container_id, end_index, file_id, 3 more } or object { file_id, index, type }` + + The annotations of the text output. + + - `FileCitation object { file_id, filename, index, type }` + + A citation to a file. + + - `file_id: string` + + The ID of the file. + + - `filename: string` + + The filename of the file cited. + + - `index: number` + + The index of the file in the list of files. + + - `type: "file_citation"` + + The type of the file citation. Always `file_citation`. + + - `"file_citation"` + + - `URLCitation object { end_index, start_index, title, 2 more }` + + A citation for a web resource used to generate a model response. + + - `end_index: number` + + The index of the last character of the URL citation in the message. + + - `start_index: number` + + The index of the first character of the URL citation in the message. + + - `title: string` + + The title of the web resource. + + - `type: "url_citation"` + + The type of the URL citation. Always `url_citation`. + + - `"url_citation"` + + - `url: string` + + The URL of the web resource. + + - `ContainerFileCitation object { container_id, end_index, file_id, 3 more }` + + A citation for a container file used to generate a model response. + + - `container_id: string` + + The ID of the container file. + + - `end_index: number` + + The index of the last character of the container file citation in the message. + + - `file_id: string` + + The ID of the file. + + - `filename: string` + + The filename of the container file cited. + + - `start_index: number` + + The index of the first character of the container file citation in the message. + + - `type: "container_file_citation"` + + The type of the container file citation. Always `container_file_citation`. + + - `"container_file_citation"` + + - `FilePath object { file_id, index, type }` + + A path to a file. + + - `file_id: string` + + The ID of the file. + + - `index: number` + + The index of the file in the list of files. + + - `type: "file_path"` + + The type of the file path. Always `file_path`. + + - `"file_path"` + + - `logprobs: array of object { token, bytes, logprob, top_logprobs }` + + - `token: string` + + - `bytes: array of number` + + - `logprob: number` + + - `top_logprobs: array of object { token, bytes, logprob }` + + - `token: string` + + - `bytes: array of number` + + - `logprob: number` + + - `text: string` + + The text output from the model. + + - `type: "output_text"` + + The type of the output text. Always `output_text`. + + - `"output_text"` + + - `TextContent object { text, type }` + + A text content. + + - `text: string` + + - `type: "text"` + + - `"text"` + + - `SummaryTextContent object { text, type }` + + A summary text from the model. + + - `text: string` + + A summary of the reasoning output from the model so far. + + - `type: "summary_text"` + + The type of the object. Always `summary_text`. + + - `"summary_text"` + + - `ReasoningText object { text, type }` + + Reasoning text from the model. + + - `text: string` + + The reasoning text from the model. + + - `type: "reasoning_text"` + + The type of the reasoning text. Always `reasoning_text`. + + - `"reasoning_text"` + + - `ResponseOutputRefusal object { refusal, type }` + + A refusal from the model. + + - `refusal: string` + + The refusal explanation from the model. + + - `type: "refusal"` + + The type of the refusal. Always `refusal`. + + - `"refusal"` + + - `ResponseInputImage object { detail, type, file_id, image_url }` + + An image input to the model. Learn about [image inputs](/docs/guides/vision). + + - `detail: "low" or "high" or "auto" or "original"` + + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + + - `"low"` + + - `"high"` + + - `"auto"` + + - `"original"` + + - `type: "input_image"` + + The type of the input item. Always `input_image`. + + - `"input_image"` + + - `file_id: optional string` + + The ID of the file to be sent to the model. + + - `image_url: optional string` + + 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 }` + + A screenshot of a computer. + + - `detail: "low" or "high" or "auto" or "original"` + + The detail level of the screenshot image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + + - `"low"` + + - `"high"` - The type of item to reference. Always `item_reference`. + - `"auto"` - - `"item_reference"` + - `"original"` -- `metadata: optional Metadata` + - `file_id: string` - Set of 16 key-value pairs that can be attached to an object. This can be - useful for storing additional information about the object in a structured - format, and querying for objects via API or the dashboard. + The identifier of an uploaded file that contains the screenshot. - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + - `image_url: string` -### Returns + The URL of the screenshot image. -- `Conversation object { id, created_at, metadata, object }` + - `type: "computer_screenshot"` - - `id: string` + Specifies the event type. For a computer screenshot, this property is always set to `computer_screenshot`. - The unique ID of the conversation. + - `"computer_screenshot"` - - `created_at: number` + - `ResponseInputFile object { type, detail, file_data, 3 more }` - The time at which the conversation was created, measured in seconds since the Unix epoch. + A file input to the model. - - `metadata: unknown` + - `type: "input_file"` - Set of 16 key-value pairs that can be attached to an object. This can be useful for storing additional information about the object in a structured format, and querying for objects via API or the dashboard. - Keys are strings with a maximum length of 64 characters. Values are strings with a maximum length of 512 characters. + The type of the input item. Always `input_file`. - - `object: "conversation"` + - `"input_file"` - The object type, which is always `conversation`. + - `detail: optional "low" or "high"` - - `"conversation"` + 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`. -### Example + - `"low"` -```http -curl https://api.openai.com/v1/conversations \ - -X POST \ - -H "Authorization: Bearer $OPENAI_API_KEY" -``` + - `"high"` -#### Response + - `file_data: optional string` -```json -{ - "id": "id", - "created_at": 0, - "metadata": {}, - "object": "conversation" -} -``` + The content of the file to be sent to the model. -### Example + - `file_id: optional string` -```http -curl https://api.openai.com/v1/conversations \ - -H "Content-Type: application/json" \ - -H "Authorization: Bearer $OPENAI_API_KEY" \ - -d '{ - "metadata": {"topic": "demo"}, - "items": [ - { - "type": "message", - "role": "user", - "content": "Hello!" - } - ] - }' -``` + The ID of the file to be sent to the model. -#### Response + - `file_url: optional string` -```json -{ - "id": "conv_123", - "object": "conversation", - "created_at": 1741900000, - "metadata": {"topic": "demo"} -} -``` + The URL of the file to be sent to the model. -## Retrieve a conversation + - `filename: optional string` -**get** `/conversations/{conversation_id}` + The name of the file to be sent to the model. -Get a conversation + - `role: "unknown" or "user" or "assistant" or 5 more` -### Path Parameters + The role of the message. One of `unknown`, `user`, `assistant`, `system`, `critic`, `discriminator`, `developer`, or `tool`. -- `conversation_id: string` + - `"unknown"` -### Returns + - `"user"` -- `Conversation object { id, created_at, metadata, object }` + - `"assistant"` - - `id: string` + - `"system"` - The unique ID of the conversation. + - `"critic"` - - `created_at: number` + - `"discriminator"` - The time at which the conversation was created, measured in seconds since the Unix epoch. + - `"developer"` - - `metadata: unknown` + - `"tool"` - Set of 16 key-value pairs that can be attached to an object. This can be useful for storing additional information about the object in a structured format, and querying for objects via API or the dashboard. - Keys are strings with a maximum length of 64 characters. Values are strings with a maximum length of 512 characters. + - `status: "in_progress" or "completed" or "incomplete"` - - `object: "conversation"` + The status of item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. - The object type, which is always `conversation`. + - `"in_progress"` - - `"conversation"` + - `"completed"` -### Example + - `"incomplete"` -```http -curl https://api.openai.com/v1/conversations/$CONVERSATION_ID \ - -H "Authorization: Bearer $OPENAI_API_KEY" -``` + - `type: "message"` -#### Response + The type of the message. Always set to `message`. -```json -{ - "id": "id", - "created_at": 0, - "metadata": {}, - "object": "conversation" -} -``` + - `"message"` -### Example + - `phase: optional "commentary" or "final_answer"` -```http -curl https://api.openai.com/v1/conversations/conv_123 \ - -H "Authorization: Bearer $OPENAI_API_KEY" -``` + Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend phase on all assistant messages — dropping it can degrade performance. Not used for user messages. -#### Response + - `"commentary"` -```json -{ - "id": "conv_123", - "object": "conversation", - "created_at": 1741900000, - "metadata": {"topic": "demo"} -} -``` + - `"final_answer"` -## Update a conversation + - `FunctionCall object { id, arguments, call_id, 5 more }` -**post** `/conversations/{conversation_id}` + - `id: string` -Update a conversation + The unique ID of the function tool call. -### Path Parameters + - `arguments: string` -- `conversation_id: string` + A JSON string of the arguments to pass to the function. -### Body Parameters + - `call_id: string` -- `metadata: Metadata` + The unique ID of the function tool call generated by the model. - Set of 16 key-value pairs that can be attached to an object. This can be - useful for storing additional information about the object in a structured - format, and querying for objects via API or the dashboard. + - `name: string` - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + The name of the function to run. -### Returns + - `status: "in_progress" or "completed" or "incomplete"` -- `Conversation object { id, created_at, metadata, object }` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `type: "function_call"` + + The type of the function tool call. Always `function_call`. + + - `"function_call"` + + - `created_by: optional string` + + The identifier of the actor that created the item. + + - `namespace: optional string` + + The namespace of the function to run. + + - `FunctionCallOutput object { id, call_id, output, 3 more }` - `id: string` - The unique ID of the conversation. + The unique ID of the function call tool output. - - `created_at: number` + - `call_id: string` - The time at which the conversation was created, measured in seconds since the Unix epoch. + The unique ID of the function tool call generated by the model. - - `metadata: unknown` + - `output: string or array of ResponseInputText or ResponseInputImage or ResponseInputFile` - Set of 16 key-value pairs that can be attached to an object. This can be useful for storing additional information about the object in a structured format, and querying for objects via API or the dashboard. - Keys are strings with a maximum length of 64 characters. Values are strings with a maximum length of 512 characters. + The output from the function call generated by your code. + Can be a string or an list of output content. - - `object: "conversation"` + - `StringOutput = string` - The object type, which is always `conversation`. + A string of the output of the function call. - - `"conversation"` + - `OutputContentList = array of ResponseInputText or ResponseInputImage or ResponseInputFile` -### Example + Text, image, or file output of the function call. -```http -curl https://api.openai.com/v1/conversations/$CONVERSATION_ID \ - -H 'Content-Type: application/json' \ - -H "Authorization: Bearer $OPENAI_API_KEY" \ - -d '{ - "metadata": { - "foo": "string" - } - }' -``` + - `ResponseInputText object { text, type }` -#### Response + A text input to the model. -```json -{ - "id": "id", - "created_at": 0, - "metadata": {}, - "object": "conversation" -} -``` + - `ResponseInputImage object { detail, type, file_id, image_url }` -### Example + An image input to the model. Learn about [image inputs](/docs/guides/vision). -```http -curl https://api.openai.com/v1/conversations/conv_123 \ - -H "Content-Type: application/json" \ - -H "Authorization: Bearer $OPENAI_API_KEY" \ - -d '{ - "metadata": {"topic": "project-x"} - }' -``` + - `ResponseInputFile object { type, detail, file_data, 3 more }` + + A file input to the model. -#### Response + - `status: "in_progress" or "completed" or "incomplete"` -```json -{ - "id": "conv_123", - "object": "conversation", - "created_at": 1741900000, - "metadata": {"topic": "project-x"} -} -``` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. -## Delete a conversation + - `"in_progress"` -**delete** `/conversations/{conversation_id}` + - `"completed"` -Delete a conversation. Items in the conversation will not be deleted. + - `"incomplete"` -### Path Parameters + - `type: "function_call_output"` -- `conversation_id: string` + The type of the function tool call output. Always `function_call_output`. -### Returns + - `"function_call_output"` -- `ConversationDeletedResource object { id, deleted, object }` + - `created_by: optional string` + + The identifier of the actor that created the item. + + - `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. - `id: string` - - `deleted: boolean` + The unique ID of the file search tool call. - - `object: "conversation.deleted"` + - `queries: array of string` - - `"conversation.deleted"` + The queries used to search for files. -### Example + - `status: "in_progress" or "searching" or "completed" or 2 more` -```http -curl https://api.openai.com/v1/conversations/$CONVERSATION_ID \ - -X DELETE \ - -H "Authorization: Bearer $OPENAI_API_KEY" -``` + The status of the file search tool call. One of `in_progress`, + `searching`, `incomplete` or `failed`, -#### Response + - `"in_progress"` -```json -{ - "id": "id", - "deleted": true, - "object": "conversation.deleted" -} -``` + - `"searching"` -### Example + - `"completed"` -```http -curl -X DELETE https://api.openai.com/v1/conversations/conv_123 \ - -H "Authorization: Bearer $OPENAI_API_KEY" -``` + - `"incomplete"` -#### Response + - `"failed"` -```json -{ - "id": "conv_123", - "object": "conversation.deleted", - "deleted": true -} -``` + - `type: "file_search_call"` -## Domain Types + The type of the file search tool call. Always `file_search_call`. -### Computer Screenshot Content + - `"file_search_call"` -- `ComputerScreenshotContent object { detail, file_id, image_url, type }` + - `results: optional array of object { attributes, file_id, filename, 2 more }` - A screenshot of a computer. + The results of the file search tool call. - - `detail: "low" or "high" or "auto" or "original"` + - `attributes: optional map[string or number or boolean]` - The detail level of the screenshot image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + Set of 16 key-value pairs that can be attached to an object. This can be + useful for storing additional information about the object in a structured + format, and querying for objects via API or the dashboard. Keys are strings + with a maximum length of 64 characters. Values are strings with a maximum + length of 512 characters, booleans, or numbers. - - `"low"` + - `string` - - `"high"` + - `number` - - `"auto"` + - `boolean` - - `"original"` + - `file_id: optional string` - - `file_id: string` + The unique ID of the file. - The identifier of an uploaded file that contains the screenshot. + - `filename: optional string` - - `image_url: string` + The name of the file. - The URL of the screenshot image. + - `score: optional number` - - `type: "computer_screenshot"` + The relevance score of the file - a value between 0 and 1. - Specifies the event type. For a computer screenshot, this property is always set to `computer_screenshot`. + - `text: optional string` - - `"computer_screenshot"` + The text that was retrieved from the file. -### Conversation + - `WebSearchCall object { id, action, status, type }` -- `Conversation object { id, created_at, metadata, object }` + The results of a web search tool call. See the + [web search guide](/docs/guides/tools-web-search) for more information. - `id: string` - The unique ID of the conversation. + The unique ID of the web search tool call. - - `created_at: number` + - `action: object { type, queries, query, sources } or object { type, url } or object { pattern, type, url }` - The time at which the conversation was created, measured in seconds since the Unix epoch. + An object describing the specific action taken in this web search call. + Includes details on how the model used the web (search, open_page, find_in_page). - - `metadata: unknown` + - `Search object { type, queries, query, sources }` - Set of 16 key-value pairs that can be attached to an object. This can be useful for storing additional information about the object in a structured format, and querying for objects via API or the dashboard. - Keys are strings with a maximum length of 64 characters. Values are strings with a maximum length of 512 characters. + Action type "search" - Performs a web search query. - - `object: "conversation"` + - `type: "search"` - The object type, which is always `conversation`. + The action type. - - `"conversation"` + - `"search"` -### Conversation Deleted + - `queries: optional array of string` -- `ConversationDeleted object { id, deleted, object }` + The search queries. - - `id: string` + - `query: optional string` - - `deleted: boolean` + The search query. - - `object: "conversation.deleted"` + - `sources: optional array of object { type, url }` - - `"conversation.deleted"` + The sources used in the search. -### Conversation Deleted Resource + - `type: "url"` -- `ConversationDeletedResource object { id, deleted, object }` + The type of source. Always `url`. - - `id: string` + - `"url"` - - `deleted: boolean` + - `url: string` - - `object: "conversation.deleted"` + The URL of the source. - - `"conversation.deleted"` + - `OpenPage object { type, url }` -### Message + Action type "open_page" - Opens a specific URL from search results. -- `Message object { id, content, role, 3 more }` + - `type: "open_page"` - A message to or from the model. + The action type. - - `id: string` + - `"open_page"` - The unique ID of the message. + - `url: optional string` - - `content: array of ResponseInputText or ResponseOutputText or TextContent or 6 more` + The URL opened by the model. - The content of the message + - `FindInPage object { pattern, type, url }` - - `ResponseInputText object { text, type }` + Action type "find_in_page": Searches for a pattern within a loaded page. - A text input to the model. + - `pattern: string` - - `text: string` + The pattern or text to search for within the page. - The text input to the model. + - `type: "find_in_page"` - - `type: "input_text"` + The action type. - The type of the input item. Always `input_text`. + - `"find_in_page"` - - `"input_text"` + - `url: string` - - `ResponseOutputText object { annotations, logprobs, text, type }` + The URL of the page searched for the pattern. - A text output from the model. + - `status: "in_progress" or "searching" or "completed" or "failed"` - - `annotations: array of object { file_id, filename, index, type } or object { end_index, start_index, title, 2 more } or object { container_id, end_index, file_id, 3 more } or object { file_id, index, type }` + The status of the web search tool call. - The annotations of the text output. + - `"in_progress"` - - `FileCitation object { file_id, filename, index, type }` + - `"searching"` - A citation to a file. + - `"completed"` - - `file_id: string` + - `"failed"` - The ID of the file. + - `type: "web_search_call"` - - `filename: string` + The type of the web search tool call. Always `web_search_call`. - The filename of the file cited. + - `"web_search_call"` - - `index: number` + - `ImageGenerationCall object { id, result, status, type }` - The index of the file in the list of files. + An image generation request made by the model. - - `type: "file_citation"` + - `id: string` - The type of the file citation. Always `file_citation`. + The unique ID of the image generation call. - - `"file_citation"` + - `result: string` - - `URLCitation object { end_index, start_index, title, 2 more }` + The generated image encoded in base64. - A citation for a web resource used to generate a model response. + - `status: "in_progress" or "completed" or "generating" or "failed"` - - `end_index: number` + The status of the image generation call. - The index of the last character of the URL citation in the message. + - `"in_progress"` - - `start_index: number` + - `"completed"` - The index of the first character of the URL citation in the message. + - `"generating"` - - `title: string` + - `"failed"` - The title of the web resource. + - `type: "image_generation_call"` - - `type: "url_citation"` + The type of the image generation call. Always `image_generation_call`. - The type of the URL citation. Always `url_citation`. + - `"image_generation_call"` - - `"url_citation"` + - `ComputerCall object { id, call_id, pending_safety_checks, 4 more }` - - `url: string` + A tool call to a computer use tool. See the + [computer use guide](/docs/guides/tools-computer-use) for more information. - The URL of the web resource. + - `id: string` + + The unique ID of the computer call. + + - `call_id: string` + + An identifier used when responding to the tool call with output. + + - `pending_safety_checks: array of object { id, code, message }` + + The pending safety checks for the computer call. + + - `id: string` + + The ID of the pending safety check. + + - `code: optional string` - - `ContainerFileCitation object { container_id, end_index, file_id, 3 more }` + The type of the pending safety check. - A citation for a container file used to generate a model response. + - `message: optional string` - - `container_id: string` + Details about the pending safety check. - The ID of the container file. + - `status: "in_progress" or "completed" or "incomplete"` - - `end_index: number` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - The index of the last character of the container file citation in the message. + - `"in_progress"` - - `file_id: string` + - `"completed"` - The ID of the file. + - `"incomplete"` - - `filename: string` + - `type: "computer_call"` - The filename of the container file cited. + The type of the computer call. Always `computer_call`. - - `start_index: number` + - `"computer_call"` - The index of the first character of the container file citation in the message. + - `action: optional ComputerAction` - - `type: "container_file_citation"` + A click action. - The type of the container file citation. Always `container_file_citation`. + - `Click object { button, type, x, 2 more }` - - `"container_file_citation"` + A click action. - - `FilePath object { file_id, index, type }` + - `button: "left" or "right" or "wheel" or 2 more` - A path to a file. + Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. - - `file_id: string` + - `"left"` - The ID of the file. + - `"right"` - - `index: number` + - `"wheel"` - The index of the file in the list of files. + - `"back"` - - `type: "file_path"` + - `"forward"` - The type of the file path. Always `file_path`. + - `type: "click"` - - `"file_path"` + Specifies the event type. For a click action, this property is always `click`. - - `logprobs: array of object { token, bytes, logprob, top_logprobs }` + - `"click"` - - `token: string` + - `x: number` - - `bytes: array of number` + The x-coordinate where the click occurred. - - `logprob: number` + - `y: number` - - `top_logprobs: array of object { token, bytes, logprob }` + The y-coordinate where the click occurred. - - `token: string` + - `keys: optional array of string` - - `bytes: array of number` + The keys being held while clicking. - - `logprob: number` + - `DoubleClick object { keys, type, x, y }` - - `text: string` + A double click action. - The text output from the model. + - `keys: array of string` - - `type: "output_text"` + The keys being held while double-clicking. - The type of the output text. Always `output_text`. + - `type: "double_click"` - - `"output_text"` + Specifies the event type. For a double click action, this property is always set to `double_click`. - - `TextContent object { text, type }` + - `"double_click"` - A text content. + - `x: number` - - `text: string` + The x-coordinate where the double click occurred. - - `type: "text"` + - `y: number` - - `"text"` + The y-coordinate where the double click occurred. - - `SummaryTextContent object { text, type }` + - `Drag object { path, type, keys }` - A summary text from the model. + A drag action. - - `text: string` + - `path: array of object { x, y }` - A summary of the reasoning output from the model so far. + An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg - - `type: "summary_text"` + ``` + [ + { x: 100, y: 200 }, + { x: 200, y: 300 } + ] + ``` - The type of the object. Always `summary_text`. + - `x: number` - - `"summary_text"` + The x-coordinate. - - `ReasoningText object { text, type }` + - `y: number` - Reasoning text from the model. + The y-coordinate. - - `text: string` + - `type: "drag"` - The reasoning text from the model. + Specifies the event type. For a drag action, this property is always set to `drag`. - - `type: "reasoning_text"` + - `"drag"` - The type of the reasoning text. Always `reasoning_text`. + - `keys: optional array of string` - - `"reasoning_text"` + The keys being held while dragging the mouse. - - `ResponseOutputRefusal object { refusal, type }` + - `Keypress object { keys, type }` - A refusal from the model. + A collection of keypresses the model would like to perform. - - `refusal: string` + - `keys: array of string` - The refusal explanation from the model. + The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. - - `type: "refusal"` + - `type: "keypress"` - The type of the refusal. Always `refusal`. + Specifies the event type. For a keypress action, this property is always set to `keypress`. - - `"refusal"` + - `"keypress"` - - `ResponseInputImage object { detail, type, file_id, image_url }` + - `Move object { type, x, y, keys }` - An image input to the model. Learn about [image inputs](/docs/guides/vision). + A mouse move action. - - `detail: "low" or "high" or "auto" or "original"` + - `type: "move"` - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + Specifies the event type. For a move action, this property is always set to `move`. - - `"low"` + - `"move"` - - `"high"` + - `x: number` - - `"auto"` + The x-coordinate to move to. - - `"original"` + - `y: number` - - `type: "input_image"` + The y-coordinate to move to. - The type of the input item. Always `input_image`. + - `keys: optional array of string` - - `"input_image"` + The keys being held while moving the mouse. - - `file_id: optional string` + - `Screenshot object { type }` - The ID of the file to be sent to the model. + A screenshot action. - - `image_url: optional string` + - `type: "screenshot"` - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + Specifies the event type. For a screenshot action, this property is always set to `screenshot`. - - `ComputerScreenshotContent object { detail, file_id, image_url, type }` + - `"screenshot"` - A screenshot of a computer. + - `Scroll object { scroll_x, scroll_y, type, 3 more }` - - `detail: "low" or "high" or "auto" or "original"` + A scroll action. - The detail level of the screenshot image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + - `scroll_x: number` - - `"low"` + The horizontal scroll distance. - - `"high"` + - `scroll_y: number` - - `"auto"` + The vertical scroll distance. - - `"original"` + - `type: "scroll"` - - `file_id: string` + Specifies the event type. For a scroll action, this property is always set to `scroll`. - The identifier of an uploaded file that contains the screenshot. + - `"scroll"` - - `image_url: string` + - `x: number` - The URL of the screenshot image. + The x-coordinate where the scroll occurred. - - `type: "computer_screenshot"` + - `y: number` - Specifies the event type. For a computer screenshot, this property is always set to `computer_screenshot`. + The y-coordinate where the scroll occurred. - - `"computer_screenshot"` + - `keys: optional array of string` - - `ResponseInputFile object { type, detail, file_data, 3 more }` + The keys being held while scrolling. - A file input to the model. + - `Type object { text, type }` - - `type: "input_file"` + An action to type in text. - The type of the input item. Always `input_file`. + - `text: string` - - `"input_file"` + The text to type. - - `detail: optional "low" or "high"` + - `type: "type"` - 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`. + Specifies the event type. For a type action, this property is always set to `type`. - - `"low"` + - `"type"` - - `"high"` + - `Wait object { type }` - - `file_data: optional string` + A wait action. - The content of the file to be sent to the model. + - `type: "wait"` - - `file_id: optional string` + Specifies the event type. For a wait action, this property is always set to `wait`. - The ID of the file to be sent to the model. + - `"wait"` - - `file_url: optional string` + - `actions: optional ComputerActionList` - The URL of the file to be sent to the model. + Flattened batched actions for `computer_use`. Each action includes an + `type` discriminator and action-specific fields. - - `filename: optional string` + - `Click object { button, type, x, 2 more }` - The name of the file to be sent to the model. + A click action. - - `role: "unknown" or "user" or "assistant" or 5 more` + - `DoubleClick object { keys, type, x, y }` - The role of the message. One of `unknown`, `user`, `assistant`, `system`, `critic`, `discriminator`, `developer`, or `tool`. + A double click action. - - `"unknown"` + - `Drag object { path, type, keys }` - - `"user"` + A drag action. - - `"assistant"` + - `Keypress object { keys, type }` - - `"system"` + A collection of keypresses the model would like to perform. - - `"critic"` + - `Move object { type, x, y, keys }` - - `"discriminator"` + A mouse move action. - - `"developer"` + - `Screenshot object { type }` - - `"tool"` + A screenshot action. - - `status: "in_progress" or "completed" or "incomplete"` + - `Scroll object { scroll_x, scroll_y, type, 3 more }` - The status of item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. + A scroll action. - - `"in_progress"` + - `Type object { text, type }` - - `"completed"` + An action to type in text. - - `"incomplete"` + - `Wait object { type }` - - `type: "message"` + A wait action. - The type of the message. Always set to `message`. + - `ComputerCallOutput object { id, call_id, output, 4 more }` - - `"message"` + - `id: string` - - `phase: optional "commentary" or "final_answer"` + The unique ID of the computer call tool output. - Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend phase on all assistant messages — dropping it can degrade performance. Not used for user messages. + - `call_id: string` - - `"commentary"` + The ID of the computer tool call that produced the output. - - `"final_answer"` + - `output: ResponseComputerToolCallOutputScreenshot` -### Summary Text Content + A computer screenshot image used with the computer use tool. -- `SummaryTextContent object { text, type }` + - `type: "computer_screenshot"` - A summary text from the model. + Specifies the event type. For a computer screenshot, this property is + always set to `computer_screenshot`. - - `text: string` + - `"computer_screenshot"` - A summary of the reasoning output from the model so far. + - `file_id: optional string` - - `type: "summary_text"` + The identifier of an uploaded file that contains the screenshot. - The type of the object. Always `summary_text`. + - `image_url: optional string` - - `"summary_text"` + The URL of the screenshot image. -### Text Content + - `status: "completed" or "incomplete" or "failed" or "in_progress"` -- `TextContent object { text, type }` + The status of the message input. One of `in_progress`, `completed`, or + `incomplete`. Populated when input items are returned via API. - A text content. + - `"completed"` - - `text: string` + - `"incomplete"` - - `type: "text"` + - `"failed"` - - `"text"` + - `"in_progress"` -# Items + - `type: "computer_call_output"` -## Create items + The type of the computer tool call output. Always `computer_call_output`. -**post** `/conversations/{conversation_id}/items` + - `"computer_call_output"` -Create items in a conversation with the given ID. + - `acknowledged_safety_checks: optional array of object { id, code, message }` -### Path Parameters + The safety checks reported by the API that have been acknowledged by the + developer. -- `conversation_id: string` + - `id: string` -### Query Parameters + The ID of the pending safety check. -- `include: optional array of ResponseIncludable` + - `code: optional string` - 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. + The type of the pending safety check. - - `"file_search_call.results"` + - `message: optional string` - - `"web_search_call.results"` + Details about the pending safety check. - - `"web_search_call.action.sources"` + - `created_by: optional string` - - `"message.input_image.image_url"` + The identifier of the actor that created the item. - - `"computer_call_output.output.image_url"` + - `ToolSearchCall object { id, arguments, call_id, 4 more }` - - `"code_interpreter_call.outputs"` + - `id: string` - - `"reasoning.encrypted_content"` + The unique ID of the tool search call item. - - `"message.output_text.logprobs"` + - `arguments: unknown` -### Body Parameters + Arguments used for the tool search call. -- `items: array of EasyInputMessage or object { content, role, status, type } or ResponseOutputMessage or 26 more` + - `call_id: string` - The items to add to the conversation. You may add up to 20 items at a time. + The unique ID of the tool search call generated by the model. - - `EasyInputMessage object { content, role, phase, type }` + - `execution: "server" or "client"` - A message input to the model with a role indicating instruction following - hierarchy. Instructions given with the `developer` or `system` role take - precedence over instructions given with the `user` role. Messages with the - `assistant` role are presumed to have been generated by the model in previous - interactions. + Whether tool search was executed by the server or by the client. - - `content: string or ResponseInputMessageContentList` + - `"server"` - Text, image, or audio input to the model, used to generate a response. - Can also contain previous assistant responses. + - `"client"` - - `TextInput = string` + - `status: "in_progress" or "completed" or "incomplete"` - A text input to the model. + The status of the tool search call item that was recorded. - - `ResponseInputMessageContentList = array of ResponseInputContent` + - `"in_progress"` - A list of one or many input items to the model, containing different content - types. + - `"completed"` - - `ResponseInputText object { text, type }` + - `"incomplete"` - A text input to the model. + - `type: "tool_search_call"` - - `text: string` + The type of the item. Always `tool_search_call`. - The text input to the model. + - `"tool_search_call"` - - `type: "input_text"` + - `created_by: optional string` - The type of the input item. Always `input_text`. + The identifier of the actor that created the item. - - `"input_text"` + - `ToolSearchOutput object { id, call_id, execution, 4 more }` - - `ResponseInputImage object { detail, type, file_id, image_url }` + - `id: string` - An image input to the model. Learn about [image inputs](/docs/guides/vision). + The unique ID of the tool search output item. - - `detail: "low" or "high" or "auto" or "original"` + - `call_id: string` - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + The unique ID of the tool search call generated by the model. - - `"low"` + - `execution: "server" or "client"` - - `"high"` + Whether tool search was executed by the server or by the client. - - `"auto"` + - `"server"` - - `"original"` + - `"client"` - - `type: "input_image"` + - `status: "in_progress" or "completed" or "incomplete"` - The type of the input item. Always `input_image`. + The status of the tool search output item that was recorded. - - `"input_image"` + - `"in_progress"` - - `file_id: optional string` + - `"completed"` - The ID of the file to be sent to the model. + - `"incomplete"` - - `image_url: optional string` + - `tools: array of object { name, parameters, strict, 3 more } or object { type, vector_store_ids, filters, 2 more } or object { type } or 12 more` - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + The loaded tool definitions returned by tool search. - - `ResponseInputFile object { type, detail, file_data, 3 more }` + - `Function object { name, parameters, strict, 3 more }` - A file input to the model. + Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). - - `type: "input_file"` + - `name: string` - The type of the input item. Always `input_file`. + The name of the function to call. - - `"input_file"` + - `parameters: map[unknown]` - - `detail: optional "low" or "high"` + A JSON schema object describing the parameters of the function. - 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`. + - `strict: boolean` - - `"low"` + Whether to enforce strict parameter validation. Default `true`. - - `"high"` + - `type: "function"` - - `file_data: optional string` + The type of the function tool. Always `function`. - The content of the file to be sent to the model. + - `"function"` - - `file_id: optional string` + - `defer_loading: optional boolean` - The ID of the file to be sent to the model. + Whether this function is deferred and loaded via tool search. - - `file_url: optional string` + - `description: optional string` - The URL of the file to be sent to the model. + A description of the function. Used by the model to determine whether or not to call the function. - - `filename: optional string` + - `FileSearch object { type, vector_store_ids, filters, 2 more }` - The name of the file to be sent to the model. + 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). - - `role: "user" or "assistant" or "system" or "developer"` + - `type: "file_search"` - The role of the message input. One of `user`, `assistant`, `system`, or - `developer`. + The type of the file search tool. Always `file_search`. - - `"user"` + - `"file_search"` - - `"assistant"` + - `vector_store_ids: array of string` - - `"system"` + The IDs of the vector stores to search. - - `"developer"` + - `filters: optional ComparisonFilter or CompoundFilter` - - `phase: optional "commentary" or "final_answer"` + A filter to apply. - Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). - For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend - phase on all assistant messages — dropping it can degrade performance. Not used for user messages. + - `ComparisonFilter object { key, type, value }` - - `"commentary"` + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - - `"final_answer"` + - `key: string` - - `type: optional "message"` + The key to compare against the value. - The type of the message input. Always `message`. + - `type: "eq" or "ne" or "gt" or 5 more` - - `"message"` + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - - `Message object { content, role, status, type }` + - `eq`: equals + - `ne`: not equal + - `gt`: greater than + - `gte`: greater than or equal + - `lt`: less than + - `lte`: less than or equal + - `in`: in + - `nin`: not in - A message input to the model with a role indicating instruction following - hierarchy. Instructions given with the `developer` or `system` role take - precedence over instructions given with the `user` role. + - `"eq"` - - `content: ResponseInputMessageContentList` + - `"ne"` - A list of one or many input items to the model, containing different content - types. + - `"gt"` - - `role: "user" or "system" or "developer"` + - `"gte"` - The role of the message input. One of `user`, `system`, or `developer`. + - `"lt"` - - `"user"` + - `"lte"` - - `"system"` + - `"in"` - - `"developer"` + - `"nin"` - - `status: optional "in_progress" or "completed" or "incomplete"` + - `value: string or number or boolean or array of string or number` - The status of item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + The value to compare against the attribute key; supports string, number, or boolean types. - - `"in_progress"` + - `string` - - `"completed"` + - `number` - - `"incomplete"` + - `boolean` - - `type: optional "message"` + - `array of string or number` - The type of the message input. Always set to `message`. + - `string` - - `"message"` + - `number` - - `ResponseOutputMessage object { id, content, role, 3 more }` + - `CompoundFilter object { filters, type }` - An output message from the model. + Combine multiple filters using `and` or `or`. - - `id: string` + - `filters: array of ComparisonFilter or unknown` - The unique ID of the output message. + Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. - - `content: array of ResponseOutputText or ResponseOutputRefusal` + - `ComparisonFilter object { key, type, value }` - The content of the output message. + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - - `ResponseOutputText object { annotations, logprobs, text, type }` + - `unknown` - A text output from the model. + - `type: "and" or "or"` - - `annotations: array of object { file_id, filename, index, type } or object { end_index, start_index, title, 2 more } or object { container_id, end_index, file_id, 3 more } or object { file_id, index, type }` + Type of operation: `and` or `or`. - The annotations of the text output. + - `"and"` - - `FileCitation object { file_id, filename, index, type }` + - `"or"` - A citation to a file. + - `max_num_results: optional number` - - `file_id: string` + The maximum number of results to return. This number should be between 1 and 50 inclusive. - The ID of the file. + - `ranking_options: optional object { hybrid_search, ranker, score_threshold }` - - `filename: string` + Ranking options for search. - The filename of the file cited. + - `hybrid_search: optional object { embedding_weight, text_weight }` - - `index: number` + Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. - The index of the file in the list of files. + - `embedding_weight: number` - - `type: "file_citation"` + The weight of the embedding in the reciprocal ranking fusion. - The type of the file citation. Always `file_citation`. + - `text_weight: number` - - `"file_citation"` + The weight of the text in the reciprocal ranking fusion. - - `URLCitation object { end_index, start_index, title, 2 more }` + - `ranker: optional "auto" or "default-2024-11-15"` - A citation for a web resource used to generate a model response. + The ranker to use for the file search. - - `end_index: number` + - `"auto"` - The index of the last character of the URL citation in the message. + - `"default-2024-11-15"` - - `start_index: number` + - `score_threshold: optional number` - The index of the first character of the URL citation in the message. + The score threshold for the file search, a number between 0 and 1. Numbers closer to 1 will attempt to return only the most relevant results, but may return fewer results. - - `title: string` + - `Computer object { type }` - The title of the web resource. + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `type: "url_citation"` + - `type: "computer"` - The type of the URL citation. Always `url_citation`. + The type of the computer tool. Always `computer`. - - `"url_citation"` + - `"computer"` - - `url: string` + - `ComputerUsePreview object { display_height, display_width, environment, type }` - The URL of the web resource. + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `ContainerFileCitation object { container_id, end_index, file_id, 3 more }` + - `display_height: number` - A citation for a container file used to generate a model response. + The height of the computer display. - - `container_id: string` + - `display_width: number` - The ID of the container file. + The width of the computer display. - - `end_index: number` + - `environment: "windows" or "mac" or "linux" or 2 more` - The index of the last character of the container file citation in the message. + The type of computer environment to control. - - `file_id: string` + - `"windows"` - The ID of the file. + - `"mac"` - - `filename: string` + - `"linux"` - The filename of the container file cited. + - `"ubuntu"` - - `start_index: number` + - `"browser"` - The index of the first character of the container file citation in the message. + - `type: "computer_use_preview"` - - `type: "container_file_citation"` + The type of the computer use tool. Always `computer_use_preview`. - The type of the container file citation. Always `container_file_citation`. + - `"computer_use_preview"` - - `"container_file_citation"` + - `WebSearch object { type, filters, search_context_size, user_location }` - - `FilePath object { file_id, index, type }` + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](/docs/guides/tools-web-search). - A path to a file. + - `type: "web_search" or "web_search_2025_08_26"` - - `file_id: string` + The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. - The ID of the file. + - `"web_search"` - - `index: number` + - `"web_search_2025_08_26"` - The index of the file in the list of files. + - `filters: optional object { allowed_domains }` - - `type: "file_path"` + Filters for the search. - The type of the file path. Always `file_path`. + - `allowed_domains: optional array of string` - - `"file_path"` + Allowed domains for the search. If not provided, all domains are allowed. + Subdomains of the provided domains are allowed as well. - - `logprobs: array of object { token, bytes, logprob, top_logprobs }` + Example: `["pubmed.ncbi.nlm.nih.gov"]` - - `token: string` + - `search_context_size: optional "low" or "medium" or "high"` - - `bytes: array of number` + High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. - - `logprob: number` + - `"low"` - - `top_logprobs: array of object { token, bytes, logprob }` + - `"medium"` - - `token: string` + - `"high"` - - `bytes: array of number` + - `user_location: optional object { city, country, region, 2 more }` - - `logprob: number` + The approximate location of the user. - - `text: string` + - `city: optional string` - The text output from the model. + Free text input for the city of the user, e.g. `San Francisco`. - - `type: "output_text"` + - `country: optional string` - The type of the output text. Always `output_text`. + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - - `"output_text"` + - `region: optional string` - - `ResponseOutputRefusal object { refusal, type }` + Free text input for the region of the user, e.g. `California`. - A refusal from the model. + - `timezone: optional string` - - `refusal: string` + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - The refusal explanation from the model. + - `type: optional "approximate"` - - `type: "refusal"` + The type of location approximation. Always `approximate`. - The type of the refusal. Always `refusal`. + - `"approximate"` - - `"refusal"` + - `Mcp object { server_label, type, allowed_tools, 7 more }` - - `role: "assistant"` + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](/docs/guides/tools-remote-mcp). - The role of the output message. Always `assistant`. + - `server_label: string` - - `"assistant"` + A label for this MCP server, used to identify it in tool calls. - - `status: "in_progress" or "completed" or "incomplete"` + - `type: "mcp"` - The status of the message input. One of `in_progress`, `completed`, or - `incomplete`. Populated when input items are returned via API. + The type of the MCP tool. Always `mcp`. - - `"in_progress"` + - `"mcp"` - - `"completed"` + - `allowed_tools: optional array of string or object { read_only, tool_names }` - - `"incomplete"` + List of allowed tool names or a filter object. - - `type: "message"` + - `McpAllowedTools = array of string` - The type of the output message. Always `message`. + A string array of allowed tool names - - `"message"` + - `McpToolFilter object { read_only, tool_names }` - - `phase: optional "commentary" or "final_answer"` + A filter object to specify which tools are allowed. - Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). - For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend - phase on all assistant messages — dropping it can degrade performance. Not used for user messages. + - `read_only: optional boolean` - - `"commentary"` + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. - - `"final_answer"` + - `tool_names: optional array of string` - - `FileSearchCall object { id, queries, status, 2 more }` + List of allowed tool names. - The results of a file search tool call. See the - [file search guide](/docs/guides/tools-file-search) for more information. + - `authorization: optional string` - - `id: string` + An OAuth access token that can be used with a remote MCP server, either + with a custom MCP server URL or a service connector. Your application + must handle the OAuth authorization flow and provide the token here. - The unique ID of the file search tool call. + - `connector_id: optional "connector_dropbox" or "connector_gmail" or "connector_googlecalendar" or 5 more` - - `queries: array of string` + Identifier for service connectors, like those available in ChatGPT. One of + `server_url` or `connector_id` must be provided. Learn more about service + connectors [here](/docs/guides/tools-remote-mcp#connectors). - The queries used to search for files. + Currently supported `connector_id` values are: - - `status: "in_progress" or "searching" or "completed" or 2 more` + - Dropbox: `connector_dropbox` + - Gmail: `connector_gmail` + - Google Calendar: `connector_googlecalendar` + - Google Drive: `connector_googledrive` + - Microsoft Teams: `connector_microsoftteams` + - Outlook Calendar: `connector_outlookcalendar` + - Outlook Email: `connector_outlookemail` + - SharePoint: `connector_sharepoint` - The status of the file search tool call. One of `in_progress`, - `searching`, `incomplete` or `failed`, + - `"connector_dropbox"` - - `"in_progress"` + - `"connector_gmail"` - - `"searching"` + - `"connector_googlecalendar"` - - `"completed"` + - `"connector_googledrive"` - - `"incomplete"` + - `"connector_microsoftteams"` - - `"failed"` + - `"connector_outlookcalendar"` - - `type: "file_search_call"` + - `"connector_outlookemail"` - The type of the file search tool call. Always `file_search_call`. + - `"connector_sharepoint"` - - `"file_search_call"` + - `defer_loading: optional boolean` - - `results: optional array of object { attributes, file_id, filename, 2 more }` + Whether this MCP tool is deferred and discovered via tool search. - The results of the file search tool call. + - `headers: optional map[string]` - - `attributes: optional map[string or number or boolean]` + Optional HTTP headers to send to the MCP server. Use for authentication + or other purposes. - Set of 16 key-value pairs that can be attached to an object. This can be - useful for storing additional information about the object in a structured - format, and querying for objects via API or the dashboard. Keys are strings - with a maximum length of 64 characters. Values are strings with a maximum - length of 512 characters, booleans, or numbers. + - `require_approval: optional object { always, never } or "always" or "never"` - - `string` + Specify which of the MCP server's tools require approval. - - `number` + - `McpToolApprovalFilter object { always, never }` - - `boolean` + Specify which of the MCP server's tools require approval. Can be + `always`, `never`, or a filter object associated with tools + that require approval. - - `file_id: optional string` + - `always: optional object { read_only, tool_names }` - The unique ID of the file. + A filter object to specify which tools are allowed. - - `filename: optional string` + - `read_only: optional boolean` - The name of the file. + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. - - `score: optional number` + - `tool_names: optional array of string` - The relevance score of the file - a value between 0 and 1. + List of allowed tool names. - - `text: optional string` + - `never: optional object { read_only, tool_names }` - The text that was retrieved from the file. + A filter object to specify which tools are allowed. - - `ComputerCall object { id, call_id, pending_safety_checks, 4 more }` + - `read_only: optional boolean` - A tool call to a computer use tool. See the - [computer use guide](/docs/guides/tools-computer-use) for more information. + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. - - `id: string` + - `tool_names: optional array of string` - The unique ID of the computer call. + List of allowed tool names. - - `call_id: string` + - `McpToolApprovalSetting = "always" or "never"` - An identifier used when responding to the tool call with output. + Specify a single approval policy for all tools. One of `always` or + `never`. When set to `always`, all tools will require approval. When + set to `never`, all tools will not require approval. - - `pending_safety_checks: array of object { id, code, message }` + - `"always"` - The pending safety checks for the computer call. + - `"never"` - - `id: string` + - `server_description: optional string` - The ID of the pending safety check. + Optional description of the MCP server, used to provide more context. - - `code: optional string` + - `server_url: optional string` - The type of the pending safety check. + The URL for the MCP server. One of `server_url` or `connector_id` must be + provided. - - `message: optional string` + - `CodeInterpreter object { container, type }` - Details about the pending safety check. + A tool that runs Python code to help generate a response to a prompt. - - `status: "in_progress" or "completed" or "incomplete"` + - `container: string or object { type, file_ids, memory_limit, network_policy }` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + The code interpreter container. Can be a container ID or an object that + specifies uploaded file IDs to make available to your code, along with an + optional `memory_limit` setting. - - `"in_progress"` + - `string` - - `"completed"` + The container ID. - - `"incomplete"` + - `CodeInterpreterToolAuto object { type, file_ids, memory_limit, network_policy }` - - `type: "computer_call"` + Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. - The type of the computer call. Always `computer_call`. + - `type: "auto"` - - `"computer_call"` + Always `auto`. - - `action: optional ComputerAction` + - `"auto"` - A click action. + - `file_ids: optional array of string` - - `Click object { button, type, x, 2 more }` + An optional list of uploaded files to make available to your code. - A click action. + - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` - - `button: "left" or "right" or "wheel" or 2 more` + The memory limit for the code interpreter container. - Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. + - `"1g"` - - `"left"` + - `"4g"` - - `"right"` + - `"16g"` - - `"wheel"` + - `"64g"` - - `"back"` + - `network_policy: optional ContainerNetworkPolicyDisabled or ContainerNetworkPolicyAllowlist` - - `"forward"` + Network access policy for the container. - - `type: "click"` + - `ContainerNetworkPolicyDisabled object { type }` - Specifies the event type. For a click action, this property is always `click`. + - `type: "disabled"` - - `"click"` + Disable outbound network access. Always `disabled`. - - `x: number` + - `"disabled"` - The x-coordinate where the click occurred. + - `ContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` - - `y: number` + - `allowed_domains: array of string` - The y-coordinate where the click occurred. + A list of allowed domains when type is `allowlist`. - - `keys: optional array of string` + - `type: "allowlist"` - The keys being held while clicking. + Allow outbound network access only to specified domains. Always `allowlist`. - - `DoubleClick object { keys, type, x, y }` + - `"allowlist"` - A double click action. + - `domain_secrets: optional array of ContainerNetworkPolicyDomainSecret` - - `keys: array of string` + Optional domain-scoped secrets for allowlisted domains. - The keys being held while double-clicking. + - `domain: string` - - `type: "double_click"` + The domain associated with the secret. - Specifies the event type. For a double click action, this property is always set to `double_click`. + - `name: string` - - `"double_click"` + The name of the secret to inject for the domain. - - `x: number` + - `value: string` - The x-coordinate where the double click occurred. + The secret value to inject for the domain. - - `y: number` + - `type: "code_interpreter"` - The y-coordinate where the double click occurred. + The type of the code interpreter tool. Always `code_interpreter`. - - `Drag object { path, type, keys }` + - `"code_interpreter"` - A drag action. + - `ImageGeneration object { type, action, background, 9 more }` - - `path: array of object { x, y }` + A tool that generates images using the GPT image models. - An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg + - `type: "image_generation"` - ``` - [ - { x: 100, y: 200 }, - { x: 200, y: 300 } - ] - ``` + The type of the image generation tool. Always `image_generation`. - - `x: number` + - `"image_generation"` - The x-coordinate. + - `action: optional "generate" or "edit" or "auto"` - - `y: number` + Whether to generate a new image or edit an existing image. Default: `auto`. - The y-coordinate. + - `"generate"` - - `type: "drag"` + - `"edit"` - Specifies the event type. For a drag action, this property is always set to `drag`. + - `"auto"` - - `"drag"` + - `background: optional "transparent" or "opaque" or "auto"` - - `keys: optional array of string` + Background type for the generated image. One of `transparent`, + `opaque`, or `auto`. Default: `auto`. - The keys being held while dragging the mouse. + - `"transparent"` - - `Keypress object { keys, type }` + - `"opaque"` - A collection of keypresses the model would like to perform. + - `"auto"` - - `keys: array of string` + - `input_fidelity: optional "high" or "low"` - The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. + Control how much effort the model will exert to match the style and features, especially facial features, of input images. This parameter is only supported for `gpt-image-1` and `gpt-image-1.5` and later models, unsupported for `gpt-image-1-mini`. Supports `high` and `low`. Defaults to `low`. - - `type: "keypress"` + - `"high"` - Specifies the event type. For a keypress action, this property is always set to `keypress`. + - `"low"` - - `"keypress"` + - `input_image_mask: optional object { file_id, image_url }` - - `Move object { type, x, y, keys }` + Optional mask for inpainting. Contains `image_url` + (string, optional) and `file_id` (string, optional). - A mouse move action. + - `file_id: optional string` - - `type: "move"` + File ID for the mask image. - Specifies the event type. For a move action, this property is always set to `move`. + - `image_url: optional string` - - `"move"` + Base64-encoded mask image. - - `x: number` + - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` - The x-coordinate to move to. + The image generation model to use. Default: `gpt-image-1`. - - `y: number` + - `string` - The y-coordinate to move to. + - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` - - `keys: optional array of string` + The image generation model to use. Default: `gpt-image-1`. - The keys being held while moving the mouse. + - `"gpt-image-1"` - - `Screenshot object { type }` + - `"gpt-image-1-mini"` - A screenshot action. + - `"gpt-image-1.5"` - - `type: "screenshot"` + - `moderation: optional "auto" or "low"` - Specifies the event type. For a screenshot action, this property is always set to `screenshot`. + Moderation level for the generated image. Default: `auto`. - - `"screenshot"` + - `"auto"` - - `Scroll object { scroll_x, scroll_y, type, 3 more }` + - `"low"` - A scroll action. + - `output_compression: optional number` - - `scroll_x: number` + Compression level for the output image. Default: 100. - The horizontal scroll distance. + - `output_format: optional "png" or "webp" or "jpeg"` - - `scroll_y: number` + The output format of the generated image. One of `png`, `webp`, or + `jpeg`. Default: `png`. - The vertical scroll distance. + - `"png"` - - `type: "scroll"` + - `"webp"` - Specifies the event type. For a scroll action, this property is always set to `scroll`. + - `"jpeg"` - - `"scroll"` + - `partial_images: optional number` - - `x: number` + Number of partial images to generate in streaming mode, from 0 (default value) to 3. - The x-coordinate where the scroll occurred. + - `quality: optional "low" or "medium" or "high" or "auto"` - - `y: number` + The quality of the generated image. One of `low`, `medium`, `high`, + or `auto`. Default: `auto`. - The y-coordinate where the scroll occurred. + - `"low"` - - `keys: optional array of string` + - `"medium"` - The keys being held while scrolling. + - `"high"` - - `Type object { text, type }` + - `"auto"` - An action to type in text. + - `size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or "auto"` - - `text: string` + The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. - The text to type. + - `string` - - `type: "type"` + - `"1024x1024" or "1024x1536" or "1536x1024" or "auto"` - Specifies the event type. For a type action, this property is always set to `type`. + The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. - - `"type"` + - `"1024x1024"` - - `Wait object { type }` + - `"1024x1536"` - A wait action. + - `"1536x1024"` - - `type: "wait"` + - `"auto"` - Specifies the event type. For a wait action, this property is always set to `wait`. + - `LocalShell object { type }` - - `"wait"` + A tool that allows the model to execute shell commands in a local environment. - - `actions: optional ComputerActionList` + - `type: "local_shell"` - Flattened batched actions for `computer_use`. Each action includes an - `type` discriminator and action-specific fields. + The type of the local shell tool. Always `local_shell`. - - `Click object { button, type, x, 2 more }` + - `"local_shell"` - A click action. + - `Shell object { type, environment }` - - `DoubleClick object { keys, type, x, y }` + A tool that allows the model to execute shell commands. - A double click action. + - `type: "shell"` - - `Drag object { path, type, keys }` + The type of the shell tool. Always `shell`. - A drag action. + - `"shell"` - - `Keypress object { keys, type }` + - `environment: optional ContainerAuto or LocalEnvironment or ContainerReference` - A collection of keypresses the model would like to perform. + - `ContainerAuto object { type, file_ids, memory_limit, 2 more }` - - `Move object { type, x, y, keys }` + - `type: "container_auto"` - A mouse move action. + Automatically creates a container for this request - - `Screenshot object { type }` + - `"container_auto"` - A screenshot action. + - `file_ids: optional array of string` - - `Scroll object { scroll_x, scroll_y, type, 3 more }` + An optional list of uploaded files to make available to your code. - A scroll action. + - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` - - `Type object { text, type }` + The memory limit for the container. - An action to type in text. + - `"1g"` - - `Wait object { type }` + - `"4g"` - A wait action. + - `"16g"` - - `ComputerCallOutput object { call_id, output, type, 3 more }` + - `"64g"` - The output of a computer tool call. + - `network_policy: optional ContainerNetworkPolicyDisabled or ContainerNetworkPolicyAllowlist` - - `call_id: string` + Network access policy for the container. - The ID of the computer tool call that produced the output. + - `ContainerNetworkPolicyDisabled object { type }` - - `output: ResponseComputerToolCallOutputScreenshot` + - `ContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` - A computer screenshot image used with the computer use tool. + - `skills: optional array of SkillReference or InlineSkill` - - `type: "computer_screenshot"` + An optional list of skills referenced by id or inline data. - Specifies the event type. For a computer screenshot, this property is - always set to `computer_screenshot`. + - `SkillReference object { skill_id, type, version }` - - `"computer_screenshot"` + - `skill_id: string` - - `file_id: optional string` + The ID of the referenced skill. - The identifier of an uploaded file that contains the screenshot. + - `type: "skill_reference"` - - `image_url: optional string` + References a skill created with the /v1/skills endpoint. - The URL of the screenshot image. + - `"skill_reference"` - - `type: "computer_call_output"` + - `version: optional string` - The type of the computer tool call output. Always `computer_call_output`. + Optional skill version. Use a positive integer or 'latest'. Omit for default. - - `"computer_call_output"` + - `InlineSkill object { description, name, source, type }` - - `id: optional string` + - `description: string` - The ID of the computer tool call output. + The description of the skill. - - `acknowledged_safety_checks: optional array of object { id, code, message }` + - `name: string` - The safety checks reported by the API that have been acknowledged by the developer. + The name of the skill. - - `id: string` + - `source: InlineSkillSource` - The ID of the pending safety check. + Inline skill payload - - `code: optional string` + - `data: string` - The type of the pending safety check. + Base64-encoded skill zip bundle. - - `message: optional string` + - `media_type: "application/zip"` - Details about the pending safety check. + The media type of the inline skill payload. Must be `application/zip`. - - `status: optional "in_progress" or "completed" or "incomplete"` + - `"application/zip"` - The status of the message input. One of `in_progress`, `completed`, or `incomplete`. Populated when input items are returned via API. + - `type: "base64"` - - `"in_progress"` + The type of the inline skill source. Must be `base64`. - - `"completed"` + - `"base64"` - - `"incomplete"` + - `type: "inline"` - - `WebSearchCall object { id, action, status, type }` + Defines an inline skill for this request. - The results of a web search tool call. See the - [web search guide](/docs/guides/tools-web-search) for more information. + - `"inline"` - - `id: string` + - `LocalEnvironment object { type, skills }` - The unique ID of the web search tool call. + - `type: "local"` - - `action: object { query, type, queries, sources } or object { type, url } or object { pattern, type, url }` + Use a local computer environment. - An object describing the specific action taken in this web search call. - Includes details on how the model used the web (search, open_page, find_in_page). + - `"local"` - - `Search object { query, type, queries, sources }` + - `skills: optional array of LocalSkill` - Action type "search" - Performs a web search query. + An optional list of skills. - - `query: string` + - `description: string` - [DEPRECATED] The search query. + The description of the skill. - - `type: "search"` + - `name: string` - The action type. + The name of the skill. - - `"search"` + - `path: string` - - `queries: optional array of string` + The path to the directory containing the skill. - The search queries. + - `ContainerReference object { container_id, type }` - - `sources: optional array of object { type, url }` + - `container_id: string` - The sources used in the search. + The ID of the referenced container. - - `type: "url"` + - `type: "container_reference"` - The type of source. Always `url`. + References a container created with the /v1/containers endpoint - - `"url"` + - `"container_reference"` - - `url: string` + - `Custom object { name, type, defer_loading, 2 more }` - The URL of the source. + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) - - `OpenPage object { type, url }` + - `name: string` - Action type "open_page" - Opens a specific URL from search results. + The name of the custom tool, used to identify it in tool calls. - - `type: "open_page"` + - `type: "custom"` - The action type. + The type of the custom tool. Always `custom`. - - `"open_page"` + - `"custom"` - - `url: optional string` + - `defer_loading: optional boolean` - The URL opened by the model. + Whether this tool should be deferred and discovered via tool search. - - `FindInPage object { pattern, type, url }` + - `description: optional string` - Action type "find_in_page": Searches for a pattern within a loaded page. + Optional description of the custom tool, used to provide more context. - - `pattern: string` + - `format: optional CustomToolInputFormat` - The pattern or text to search for within the page. + The input format for the custom tool. Default is unconstrained text. - - `type: "find_in_page"` + - `Text object { type }` - The action type. + Unconstrained free-form text. - - `"find_in_page"` + - `type: "text"` - - `url: string` + Unconstrained text format. Always `text`. - The URL of the page searched for the pattern. + - `"text"` - - `status: "in_progress" or "searching" or "completed" or "failed"` + - `Grammar object { definition, syntax, type }` - The status of the web search tool call. + A grammar defined by the user. - - `"in_progress"` + - `definition: string` - - `"searching"` + The grammar definition. - - `"completed"` + - `syntax: "lark" or "regex"` - - `"failed"` + The syntax of the grammar definition. One of `lark` or `regex`. - - `type: "web_search_call"` + - `"lark"` - The type of the web search tool call. Always `web_search_call`. + - `"regex"` - - `"web_search_call"` + - `type: "grammar"` - - `FunctionCall object { arguments, call_id, name, 4 more }` + Grammar format. Always `grammar`. - A tool call to run a function. See the - [function calling guide](/docs/guides/function-calling) for more information. + - `"grammar"` - - `arguments: string` + - `Namespace object { description, name, tools, type }` - A JSON string of the arguments to pass to the function. + Groups function/custom tools under a shared namespace. - - `call_id: string` + - `description: string` - The unique ID of the function tool call generated by the model. + A description of the namespace shown to the model. - `name: string` - The name of the function to run. + The namespace name used in tool calls (for example, `crm`). - - `type: "function_call"` + - `tools: array of object { name, type, defer_loading, 3 more } or object { name, type, defer_loading, 2 more }` - The type of the function tool call. Always `function_call`. + The function/custom tools available inside this namespace. - - `"function_call"` + - `Function object { name, type, defer_loading, 3 more }` - - `id: optional string` + - `name: string` - The unique ID of the function tool call. + - `type: "function"` - - `namespace: optional string` + - `"function"` - The namespace of the function to run. + - `defer_loading: optional boolean` - - `status: optional "in_progress" or "completed" or "incomplete"` + Whether this function should be deferred and discovered via tool search. - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `description: optional string` - - `"in_progress"` + - `parameters: optional unknown` - - `"completed"` + - `strict: optional boolean` - - `"incomplete"` + - `Custom object { name, type, defer_loading, 2 more }` - - `FunctionCallOutput object { call_id, output, type, 2 more }` + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) - The output of a function tool call. + - `name: string` - - `call_id: string` + The name of the custom tool, used to identify it in tool calls. - The unique ID of the function tool call generated by the model. + - `type: "custom"` - - `output: string or array of ResponseInputTextContent or ResponseInputImageContent or ResponseInputFileContent` + The type of the custom tool. Always `custom`. - Text, image, or file output of the function tool call. + - `"custom"` - - `string` + - `defer_loading: optional boolean` - A JSON string of the output of the function tool call. + Whether this tool should be deferred and discovered via tool search. - - `array of ResponseInputTextContent or ResponseInputImageContent or ResponseInputFileContent` + - `description: optional string` - An array of content outputs (text, image, file) for the function tool call. + Optional description of the custom tool, used to provide more context. - - `ResponseInputTextContent object { text, type }` + - `format: optional CustomToolInputFormat` - A text input to the model. + The input format for the custom tool. Default is unconstrained text. - - `text: string` + - `type: "namespace"` - The text input to the model. + The type of the tool. Always `namespace`. - - `type: "input_text"` + - `"namespace"` - The type of the input item. Always `input_text`. + - `ToolSearch object { type, description, execution, parameters }` - - `"input_text"` + Hosted or BYOT tool search configuration for deferred tools. - - `ResponseInputImageContent object { type, detail, file_id, image_url }` + - `type: "tool_search"` - An image input to the model. Learn about [image inputs](/docs/guides/vision) + The type of the tool. Always `tool_search`. - - `type: "input_image"` + - `"tool_search"` - The type of the input item. Always `input_image`. + - `description: optional string` - - `"input_image"` + Description shown to the model for a client-executed tool search tool. - - `detail: optional "low" or "high" or "auto" or "original"` + - `execution: optional "server" or "client"` - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + Whether tool search is executed by the server or by the client. - - `"low"` + - `"server"` - - `"high"` + - `"client"` - - `"auto"` + - `parameters: optional unknown` - - `"original"` + Parameter schema for a client-executed tool search tool. - - `file_id: optional string` + - `WebSearchPreview object { type, search_content_types, search_context_size, user_location }` - The ID of the file to be sent to the model. + This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - - `image_url: optional string` + - `type: "web_search_preview" or "web_search_preview_2025_03_11"` - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. - - `ResponseInputFileContent object { type, detail, file_data, 3 more }` + - `"web_search_preview"` - A file input to the model. + - `"web_search_preview_2025_03_11"` - - `type: "input_file"` + - `search_content_types: optional array of "text" or "image"` - The type of the input item. Always `input_file`. + - `"text"` - - `"input_file"` + - `"image"` - - `detail: optional "low" or "high"` + - `search_context_size: optional "low" or "medium" 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`. + High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. - `"low"` - - `"high"` - - - `file_data: optional string` + - `"medium"` - The base64-encoded data of the file to be sent to the model. + - `"high"` - - `file_id: optional string` + - `user_location: optional object { type, city, country, 2 more }` - The ID of the file to be sent to the model. + The user's location. - - `file_url: optional string` + - `type: "approximate"` - The URL of the file to be sent to the model. + The type of location approximation. Always `approximate`. - - `filename: optional string` + - `"approximate"` - The name of the file to be sent to the model. + - `city: optional string` - - `type: "function_call_output"` + Free text input for the city of the user, e.g. `San Francisco`. - The type of the function tool call output. Always `function_call_output`. + - `country: optional string` - - `"function_call_output"` + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - - `id: optional string` + - `region: optional string` - The unique ID of the function tool call output. Populated when this item is returned via API. + Free text input for the region of the user, e.g. `California`. - - `status: optional "in_progress" or "completed" or "incomplete"` + - `timezone: optional string` - The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - - `"in_progress"` + - `ApplyPatch object { type }` - - `"completed"` + Allows the assistant to create, delete, or update files using unified diffs. - - `"incomplete"` + - `type: "apply_patch"` - - `ToolSearchCall object { arguments, type, id, 3 more }` + The type of the tool. Always `apply_patch`. - - `arguments: unknown` + - `"apply_patch"` - The arguments supplied to the tool search call. + - `type: "tool_search_output"` - - `type: "tool_search_call"` + The type of the item. Always `tool_search_output`. - The item type. Always `tool_search_call`. + - `"tool_search_output"` - - `"tool_search_call"` + - `created_by: optional string` - - `id: optional string` + The identifier of the actor that created the item. - The unique ID of this tool search call. + - `AdditionalTools object { id, role, tools, type }` - - `call_id: optional string` + - `id: string` - The unique ID of the tool search call generated by the model. + The unique ID of the additional tools item. - - `execution: optional "server" or "client"` + - `role: "unknown" or "user" or "assistant" or 5 more` - Whether tool search was executed by the server or by the client. + The role that provided the additional tools. - - `"server"` + - `"unknown"` - - `"client"` + - `"user"` - - `status: optional "in_progress" or "completed" or "incomplete"` + - `"assistant"` - The status of the tool search call. + - `"system"` - - `"in_progress"` + - `"critic"` - - `"completed"` + - `"discriminator"` - - `"incomplete"` + - `"developer"` - - `ToolSearchOutput object { tools, type, id, 3 more }` + - `"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` - The loaded tool definitions returned by the tool search output. + The additional tool definitions made available at this item. - `Function object { name, parameters, strict, 3 more }` @@ -4741,77 +10059,10 @@ Create items in a conversation with the given ID. A filter used to compare a specified attribute key to a given value using a defined comparison operation. - - `key: string` - - The key to compare against the value. - - - `type: "eq" or "ne" or "gt" or 5 more` - - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - - - `eq`: equals - - `ne`: not equal - - `gt`: greater than - - `gte`: greater than or equal - - `lt`: less than - - `lte`: less than or equal - - `in`: in - - `nin`: not in - - - `"eq"` - - - `"ne"` - - - `"gt"` - - - `"gte"` - - - `"lt"` - - - `"lte"` - - - `"in"` - - - `"nin"` - - - `value: string or number or boolean or array of string or number` - - The value to compare against the attribute key; supports string, number, or boolean types. - - - `string` - - - `number` - - - `boolean` - - - `array of string or number` - - - `string` - - - `number` - - `CompoundFilter object { filters, type }` Combine multiple filters using `and` or `or`. - - `filters: array of ComparisonFilter or unknown` - - Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. - - - `ComparisonFilter object { key, type, value }` - - A filter used to compare a specified attribute key to a given value using a defined comparison operation. - - - `unknown` - - - `type: "and" or "or"` - - Type of operation: `and` or `or`. - - - `"and"` - - - `"or"` - - `max_num_results: optional number` The maximum number of results to return. This number should be between 1 and 50 inclusive. @@ -5130,43 +10381,11 @@ Create items in a conversation with the given ID. - `network_policy: optional ContainerNetworkPolicyDisabled or ContainerNetworkPolicyAllowlist` - Network access policy for the container. - - - `ContainerNetworkPolicyDisabled object { type }` - - - `type: "disabled"` - - Disable outbound network access. Always `disabled`. - - - `"disabled"` - - - `ContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` - - - `allowed_domains: array of string` - - A list of allowed domains when type is `allowlist`. - - - `type: "allowlist"` - - Allow outbound network access only to specified domains. Always `allowlist`. - - - `"allowlist"` - - - `domain_secrets: optional array of ContainerNetworkPolicyDomainSecret` - - Optional domain-scoped secrets for allowlisted domains. - - - `domain: string` - - The domain associated with the secret. - - - `name: string` - - The name of the secret to inject for the domain. + Network access policy for the container. - - `value: string` + - `ContainerNetworkPolicyDisabled object { type }` - The secret value to inject for the domain. + - `ContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` - `type: "code_interpreter"` @@ -5324,367 +10543,569 @@ Create items in a conversation with the given ID. - `ContainerAuto object { type, file_ids, memory_limit, 2 more }` - - `type: "container_auto"` + - `LocalEnvironment object { type, skills }` - Automatically creates a container for this request + - `ContainerReference object { container_id, type }` - - `"container_auto"` + - `Custom object { name, type, defer_loading, 2 more }` - - `file_ids: optional array of string` + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) - An optional list of uploaded files to make available to your code. + - `name: string` - - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` + The name of the custom tool, used to identify it in tool calls. - The memory limit for the container. + - `type: "custom"` - - `"1g"` + The type of the custom tool. Always `custom`. - - `"4g"` + - `"custom"` - - `"16g"` + - `defer_loading: optional boolean` - - `"64g"` + Whether this tool should be deferred and discovered via tool search. - - `network_policy: optional ContainerNetworkPolicyDisabled or ContainerNetworkPolicyAllowlist` + - `description: optional string` - Network access policy for the container. + Optional description of the custom tool, used to provide more context. - - `ContainerNetworkPolicyDisabled object { type }` + - `format: optional CustomToolInputFormat` - - `ContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` + The input format for the custom tool. Default is unconstrained text. - - `skills: optional array of SkillReference or InlineSkill` + - `Namespace object { description, name, tools, type }` - An optional list of skills referenced by id or inline data. + Groups function/custom tools under a shared namespace. - - `SkillReference object { skill_id, type, version }` + - `description: string` - - `skill_id: string` + A description of the namespace shown to the model. - The ID of the referenced skill. + - `name: string` - - `type: "skill_reference"` + The namespace name used in tool calls (for example, `crm`). - References a skill created with the /v1/skills endpoint. + - `tools: array of object { name, type, defer_loading, 3 more } or object { name, type, defer_loading, 2 more }` - - `"skill_reference"` + The function/custom tools available inside this namespace. - - `version: optional string` + - `Function object { name, type, defer_loading, 3 more }` - Optional skill version. Use a positive integer or 'latest'. Omit for default. + - `name: string` - - `InlineSkill object { description, name, source, type }` + - `type: "function"` + + - `"function"` + + - `defer_loading: optional boolean` + + Whether this function should be deferred and discovered via tool search. + + - `description: optional string` + + - `parameters: optional unknown` + + - `strict: optional boolean` + + - `Custom object { name, type, defer_loading, 2 more }` + + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) + + - `name: string` + + The name of the custom tool, used to identify it in tool calls. + + - `type: "custom"` + + The type of the custom tool. Always `custom`. + + - `"custom"` + + - `defer_loading: optional boolean` + + Whether this tool should be deferred and discovered via tool search. + + - `description: optional string` + + Optional description of the custom tool, used to provide more context. + + - `format: optional CustomToolInputFormat` + + The input format for the custom tool. Default is unconstrained text. + + - `type: "namespace"` + + The type of the tool. Always `namespace`. + + - `"namespace"` + + - `ToolSearch object { type, description, execution, parameters }` + + Hosted or BYOT tool search configuration for deferred tools. + + - `type: "tool_search"` + + The type of the tool. Always `tool_search`. + + - `"tool_search"` + + - `description: optional string` + + Description shown to the model for a client-executed tool search tool. + + - `execution: optional "server" or "client"` + + Whether tool search is executed by the server or by the client. + + - `"server"` + + - `"client"` + + - `parameters: optional unknown` + + Parameter schema for a client-executed tool search tool. + + - `WebSearchPreview object { type, search_content_types, search_context_size, user_location }` + + This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + + - `type: "web_search_preview" or "web_search_preview_2025_03_11"` + + The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. + + - `"web_search_preview"` + + - `"web_search_preview_2025_03_11"` + + - `search_content_types: optional array of "text" or "image"` + + - `"text"` + + - `"image"` + + - `search_context_size: optional "low" or "medium" or "high"` + + High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. + + - `"low"` + + - `"medium"` + + - `"high"` + + - `user_location: optional object { type, city, country, 2 more }` + + The user's location. + + - `type: "approximate"` + + The type of location approximation. Always `approximate`. + + - `"approximate"` + + - `city: optional string` + + Free text input for the city of the user, e.g. `San Francisco`. + + - `country: optional string` + + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + + - `region: optional string` + + Free text input for the region of the user, e.g. `California`. + + - `timezone: optional string` + + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + + - `ApplyPatch object { type }` + + Allows the assistant to create, delete, or update files using unified diffs. + + - `type: "apply_patch"` + + The type of the tool. Always `apply_patch`. + + - `"apply_patch"` + + - `type: "additional_tools"` + + The type of the item. Always `additional_tools`. + + - `"additional_tools"` + + - `Reasoning object { id, summary, type, 3 more }` + + 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). + + - `id: string` + + The unique identifier of the reasoning content. + + - `summary: array of SummaryTextContent` + + Reasoning summary content. + + - `text: string` + + A summary of the reasoning output from the model so far. + + - `type: "summary_text"` + + The type of the object. Always `summary_text`. + + - `type: "reasoning"` + + The type of the object. Always `reasoning`. + + - `"reasoning"` + + - `content: optional array of object { text, type }` + + Reasoning text content. + + - `text: string` + + The reasoning text from the model. + + - `type: "reasoning_text"` + + The type of the reasoning text. Always `reasoning_text`. + + - `"reasoning_text"` + + - `encrypted_content: optional string` + + The encrypted content of the reasoning item - populated when a response is + generated with `reasoning.encrypted_content` in the `include` parameter. + + - `status: optional "in_progress" or "completed" or "incomplete"` + + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `Compaction object { id, encrypted_content, type, created_by }` - - `description: string` + A compaction item generated by the [`v1/responses/compact` API](/docs/api-reference/responses/compact). - The description of the skill. + - `id: string` - - `name: string` + The unique ID of the compaction item. - The name of the skill. + - `encrypted_content: string` - - `source: InlineSkillSource` + The encrypted content that was produced by compaction. - Inline skill payload + - `type: "compaction"` - - `data: string` + The type of the item. Always `compaction`. - Base64-encoded skill zip bundle. + - `"compaction"` - - `media_type: "application/zip"` + - `created_by: optional string` - The media type of the inline skill payload. Must be `application/zip`. + The identifier of the actor that created the item. - - `"application/zip"` + - `CodeInterpreterCall object { id, code, container_id, 3 more }` - - `type: "base64"` + A tool call to run code. - The type of the inline skill source. Must be `base64`. + - `id: string` - - `"base64"` + The unique ID of the code interpreter tool call. - - `type: "inline"` + - `code: string` - Defines an inline skill for this request. + The code to run, or null if not available. - - `"inline"` + - `container_id: string` - - `LocalEnvironment object { type, skills }` + The ID of the container used to run the code. - - `type: "local"` + - `outputs: array of object { logs, type } or object { type, url }` - Use a local computer environment. + The outputs generated by the code interpreter, such as logs or images. + Can be null if no outputs are available. - - `"local"` + - `Logs object { logs, type }` - - `skills: optional array of LocalSkill` + The logs output from the code interpreter. - An optional list of skills. + - `logs: string` - - `description: string` + The logs output from the code interpreter. - The description of the skill. + - `type: "logs"` - - `name: string` + The type of the output. Always `logs`. - The name of the skill. + - `"logs"` - - `path: string` + - `Image object { type, url }` - The path to the directory containing the skill. + The image output from the code interpreter. - - `ContainerReference object { container_id, type }` + - `type: "image"` - - `container_id: string` + The type of the output. Always `image`. - The ID of the referenced container. + - `"image"` - - `type: "container_reference"` + - `url: string` - References a container created with the /v1/containers endpoint + The URL of the image output from the code interpreter. - - `"container_reference"` + - `status: "in_progress" or "completed" or "incomplete" or 2 more` - - `Custom object { name, type, defer_loading, 2 more }` + The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. - A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) + - `"in_progress"` - - `name: string` + - `"completed"` - The name of the custom tool, used to identify it in tool calls. + - `"incomplete"` - - `type: "custom"` + - `"interpreting"` - The type of the custom tool. Always `custom`. + - `"failed"` - - `"custom"` + - `type: "code_interpreter_call"` - - `defer_loading: optional boolean` + The type of the code interpreter tool call. Always `code_interpreter_call`. - Whether this tool should be deferred and discovered via tool search. + - `"code_interpreter_call"` - - `description: optional string` + - `LocalShellCall object { id, action, call_id, 2 more }` - Optional description of the custom tool, used to provide more context. + A tool call to run a command on the local shell. - - `format: optional CustomToolInputFormat` + - `id: string` - The input format for the custom tool. Default is unconstrained text. + The unique ID of the local shell call. - - `Text object { type }` + - `action: object { command, env, type, 3 more }` - Unconstrained free-form text. + Execute a shell command on the server. - - `type: "text"` + - `command: array of string` - Unconstrained text format. Always `text`. + The command to run. - - `"text"` + - `env: map[string]` - - `Grammar object { definition, syntax, type }` + Environment variables to set for the command. - A grammar defined by the user. + - `type: "exec"` - - `definition: string` + The type of the local shell action. Always `exec`. - The grammar definition. + - `"exec"` - - `syntax: "lark" or "regex"` + - `timeout_ms: optional number` - The syntax of the grammar definition. One of `lark` or `regex`. + Optional timeout in milliseconds for the command. - - `"lark"` + - `user: optional string` - - `"regex"` + Optional user to run the command as. - - `type: "grammar"` + - `working_directory: optional string` - Grammar format. Always `grammar`. + Optional working directory to run the command in. - - `"grammar"` + - `call_id: string` - - `Namespace object { description, name, tools, type }` + The unique ID of the local shell tool call generated by the model. - Groups function/custom tools under a shared namespace. + - `status: "in_progress" or "completed" or "incomplete"` - - `description: string` + The status of the local shell call. - A description of the namespace shown to the model. + - `"in_progress"` - - `name: string` + - `"completed"` - The namespace name used in tool calls (for example, `crm`). + - `"incomplete"` - - `tools: array of object { name, type, defer_loading, 3 more } or object { name, type, defer_loading, 2 more }` + - `type: "local_shell_call"` - The function/custom tools available inside this namespace. + The type of the local shell call. Always `local_shell_call`. - - `Function object { name, type, defer_loading, 3 more }` + - `"local_shell_call"` - - `name: string` + - `LocalShellCallOutput object { id, output, type, status }` - - `type: "function"` + The output of a local shell tool call. - - `"function"` + - `id: string` - - `defer_loading: optional boolean` + The unique ID of the local shell tool call generated by the model. - Whether this function should be deferred and discovered via tool search. + - `output: string` - - `description: optional string` + A JSON string of the output of the local shell tool call. - - `parameters: optional unknown` + - `type: "local_shell_call_output"` - - `strict: optional boolean` + The type of the local shell tool call output. Always `local_shell_call_output`. - - `Custom object { name, type, defer_loading, 2 more }` + - `"local_shell_call_output"` - A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) + - `status: optional "in_progress" or "completed" or "incomplete"` - - `name: string` + The status of the item. One of `in_progress`, `completed`, or `incomplete`. - The name of the custom tool, used to identify it in tool calls. + - `"in_progress"` - - `type: "custom"` + - `"completed"` - The type of the custom tool. Always `custom`. + - `"incomplete"` - - `"custom"` + - `ShellCall object { id, action, call_id, 4 more }` - - `defer_loading: optional boolean` + A tool call that executes one or more shell commands in a managed environment. - Whether this tool should be deferred and discovered via tool search. + - `id: string` - - `description: optional string` + The unique ID of the shell tool call. Populated when this item is returned via API. - Optional description of the custom tool, used to provide more context. + - `action: object { commands, max_output_length, timeout_ms }` - - `format: optional CustomToolInputFormat` + The shell commands and limits that describe how to run the tool call. - The input format for the custom tool. Default is unconstrained text. + - `commands: array of string` - - `type: "namespace"` + - `max_output_length: number` - The type of the tool. Always `namespace`. + Optional maximum number of characters to return from each command. - - `"namespace"` + - `timeout_ms: number` - - `ToolSearch object { type, description, execution, parameters }` + Optional timeout in milliseconds for the commands. - Hosted or BYOT tool search configuration for deferred tools. + - `call_id: string` - - `type: "tool_search"` + The unique ID of the shell tool call generated by the model. - The type of the tool. Always `tool_search`. + - `environment: ResponseLocalEnvironment or ResponseContainerReference` - - `"tool_search"` + Represents the use of a local environment to perform shell actions. - - `description: optional string` + - `ResponseLocalEnvironment object { type }` - Description shown to the model for a client-executed tool search tool. + Represents the use of a local environment to perform shell actions. - - `execution: optional "server" or "client"` + - `type: "local"` - Whether tool search is executed by the server or by the client. + The environment type. Always `local`. - - `"server"` + - `"local"` - - `"client"` + - `ResponseContainerReference object { container_id, type }` - - `parameters: optional unknown` + Represents a container created with /v1/containers. - Parameter schema for a client-executed tool search tool. + - `container_id: string` - - `WebSearchPreview object { type, search_content_types, search_context_size, user_location }` + - `type: "container_reference"` - This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + The environment type. Always `container_reference`. - - `type: "web_search_preview" or "web_search_preview_2025_03_11"` + - `"container_reference"` - The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. + - `status: "in_progress" or "completed" or "incomplete"` - - `"web_search_preview"` + The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. - - `"web_search_preview_2025_03_11"` + - `"in_progress"` - - `search_content_types: optional array of "text" or "image"` + - `"completed"` - - `"text"` + - `"incomplete"` - - `"image"` + - `type: "shell_call"` - - `search_context_size: optional "low" or "medium" or "high"` + The type of the item. Always `shell_call`. - High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. + - `"shell_call"` - - `"low"` + - `created_by: optional string` - - `"medium"` + The ID of the entity that created this tool call. - - `"high"` + - `ShellCallOutput object { id, call_id, max_output_length, 4 more }` - - `user_location: optional object { type, city, country, 2 more }` + The output of a shell tool call that was emitted. - The user's location. + - `id: string` - - `type: "approximate"` + The unique ID of the shell call output. Populated when this item is returned via API. - The type of location approximation. Always `approximate`. + - `call_id: string` - - `"approximate"` + The unique ID of the shell tool call generated by the model. - - `city: optional string` + - `max_output_length: number` - Free text input for the city of the user, e.g. `San Francisco`. + The maximum length of the shell command output. This is generated by the model and should be passed back with the raw output. - - `country: optional string` + - `output: array of object { outcome, stderr, stdout, created_by }` - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + An array of shell call output contents - - `region: optional string` + - `outcome: object { type } or object { exit_code, type }` - Free text input for the region of the user, e.g. `California`. + Represents either an exit outcome (with an exit code) or a timeout outcome for a shell call output chunk. - - `timezone: optional string` + - `Timeout object { type }` - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + Indicates that the shell call exceeded its configured time limit. - - `ApplyPatch object { type }` + - `type: "timeout"` - Allows the assistant to create, delete, or update files using unified diffs. + The outcome type. Always `timeout`. - - `type: "apply_patch"` + - `"timeout"` - The type of the tool. Always `apply_patch`. + - `Exit object { exit_code, type }` - - `"apply_patch"` + Indicates that the shell commands finished and returned an exit code. - - `type: "tool_search_output"` + - `exit_code: number` - The item type. Always `tool_search_output`. + Exit code from the shell process. - - `"tool_search_output"` + - `type: "exit"` - - `id: optional string` + The outcome type. Always `exit`. - The unique ID of this tool search output. + - `"exit"` - - `call_id: optional string` + - `stderr: string` - The unique ID of the tool search call generated by the model. + The standard error output that was captured. - - `execution: optional "server" or "client"` + - `stdout: string` - Whether tool search was executed by the server or by the client. + The standard output that was captured. - - `"server"` + - `created_by: optional string` - - `"client"` + The identifier of the actor that created the item. - - `status: optional "in_progress" or "completed" or "incomplete"` + - `status: "in_progress" or "completed" or "incomplete"` - The status of the tool search output. + The status of the shell call output. One of `in_progress`, `completed`, or `incomplete`. - `"in_progress"` @@ -5692,263 +11113,270 @@ Create items in a conversation with the given ID. - `"incomplete"` - - `Reasoning object { id, summary, type, 3 more }` + - `type: "shell_call_output"` - 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). + The type of the shell call output. Always `shell_call_output`. + + - `"shell_call_output"` + + - `created_by: optional string` + + The identifier of the actor that created the item. + + - `ApplyPatchCall object { id, call_id, operation, 3 more }` + + A tool call that applies file diffs by creating, deleting, or updating files. - `id: string` - The unique identifier of the reasoning content. + The unique ID of the apply patch tool call. Populated when this item is returned via API. - - `summary: array of SummaryTextContent` + - `call_id: string` - Reasoning summary content. + The unique ID of the apply patch tool call generated by the model. - - `text: string` + - `operation: object { diff, path, type } or object { path, type } or object { diff, path, type }` - A summary of the reasoning output from the model so far. + One of the create_file, delete_file, or update_file operations applied via apply_patch. - - `type: "summary_text"` + - `CreateFile object { diff, path, type }` - The type of the object. Always `summary_text`. + Instruction describing how to create a file via the apply_patch tool. - - `"summary_text"` + - `diff: string` - - `type: "reasoning"` + Diff to apply. - The type of the object. Always `reasoning`. + - `path: string` - - `"reasoning"` + Path of the file to create. - - `content: optional array of object { text, type }` + - `type: "create_file"` - Reasoning text content. + Create a new file with the provided diff. - - `text: string` + - `"create_file"` - The reasoning text from the model. + - `DeleteFile object { path, type }` - - `type: "reasoning_text"` + Instruction describing how to delete a file via the apply_patch tool. - The type of the reasoning text. Always `reasoning_text`. + - `path: string` - - `"reasoning_text"` + Path of the file to delete. - - `encrypted_content: optional string` + - `type: "delete_file"` - The encrypted content of the reasoning item - populated when a response is - generated with `reasoning.encrypted_content` in the `include` parameter. + Delete the specified file. - - `status: optional "in_progress" or "completed" or "incomplete"` + - `"delete_file"` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `UpdateFile object { diff, path, type }` - - `"in_progress"` + Instruction describing how to update a file via the apply_patch tool. - - `"completed"` + - `diff: string` - - `"incomplete"` + Diff to apply. - - `Compaction object { encrypted_content, type, id }` + - `path: string` - A compaction item generated by the [`v1/responses/compact` API](/docs/api-reference/responses/compact). + Path of the file to update. - - `encrypted_content: string` + - `type: "update_file"` - The encrypted content of the compaction summary. + Update an existing file with the provided diff. - - `type: "compaction"` + - `"update_file"` - The type of the item. Always `compaction`. + - `status: "in_progress" or "completed"` - - `"compaction"` + The status of the apply patch tool call. One of `in_progress` or `completed`. - - `id: optional string` + - `"in_progress"` - The ID of the compaction item. + - `"completed"` - - `ImageGenerationCall object { id, result, status, type }` + - `type: "apply_patch_call"` - An image generation request made by the model. + The type of the item. Always `apply_patch_call`. - - `id: string` + - `"apply_patch_call"` - The unique ID of the image generation call. + - `created_by: optional string` - - `result: string` + The ID of the entity that created this tool call. - The generated image encoded in base64. + - `ApplyPatchCallOutput object { id, call_id, status, 3 more }` - - `status: "in_progress" or "completed" or "generating" or "failed"` + The output emitted by an apply patch tool call. - The status of the image generation call. + - `id: string` - - `"in_progress"` + The unique ID of the apply patch tool call output. Populated when this item is returned via API. - - `"completed"` + - `call_id: string` - - `"generating"` + The unique ID of the apply patch tool call generated by the model. - - `"failed"` + - `status: "completed" or "failed"` - - `type: "image_generation_call"` + The status of the apply patch tool call output. One of `completed` or `failed`. - The type of the image generation call. Always `image_generation_call`. + - `"completed"` - - `"image_generation_call"` + - `"failed"` - - `CodeInterpreterCall object { id, code, container_id, 3 more }` + - `type: "apply_patch_call_output"` - A tool call to run code. + The type of the item. Always `apply_patch_call_output`. - - `id: string` + - `"apply_patch_call_output"` - The unique ID of the code interpreter tool call. + - `created_by: optional string` - - `code: string` + The ID of the entity that created this tool call output. - The code to run, or null if not available. + - `output: optional string` - - `container_id: string` + Optional textual output returned by the apply patch tool. - The ID of the container used to run the code. + - `McpListTools object { id, server_label, tools, 2 more }` - - `outputs: array of object { logs, type } or object { type, url }` + A list of tools available on an MCP server. - The outputs generated by the code interpreter, such as logs or images. - Can be null if no outputs are available. + - `id: string` - - `Logs object { logs, type }` + The unique ID of the list. - The logs output from the code interpreter. + - `server_label: string` - - `logs: string` + The label of the MCP server. - The logs output from the code interpreter. + - `tools: array of object { input_schema, name, annotations, description }` - - `type: "logs"` + The tools available on the server. - The type of the output. Always `logs`. + - `input_schema: unknown` - - `"logs"` + The JSON schema describing the tool's input. - - `Image object { type, url }` + - `name: string` - The image output from the code interpreter. + The name of the tool. - - `type: "image"` + - `annotations: optional unknown` - The type of the output. Always `image`. + Additional annotations about the tool. - - `"image"` + - `description: optional string` - - `url: string` + The description of the tool. - The URL of the image output from the code interpreter. + - `type: "mcp_list_tools"` - - `status: "in_progress" or "completed" or "incomplete" or 2 more` + The type of the item. Always `mcp_list_tools`. - The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. + - `"mcp_list_tools"` - - `"in_progress"` + - `error: optional string` - - `"completed"` + Error message if the server could not list tools. - - `"incomplete"` + - `McpApprovalRequest object { id, arguments, name, 2 more }` - - `"interpreting"` + A request for human approval of a tool invocation. - - `"failed"` + - `id: string` - - `type: "code_interpreter_call"` + The unique ID of the approval request. - The type of the code interpreter tool call. Always `code_interpreter_call`. + - `arguments: string` - - `"code_interpreter_call"` + A JSON string of arguments for the tool. - - `LocalShellCall object { id, action, call_id, 2 more }` + - `name: string` - A tool call to run a command on the local shell. + The name of the tool to run. - - `id: string` + - `server_label: string` - The unique ID of the local shell call. + The label of the MCP server making the request. - - `action: object { command, env, type, 3 more }` + - `type: "mcp_approval_request"` - Execute a shell command on the server. + The type of the item. Always `mcp_approval_request`. - - `command: array of string` + - `"mcp_approval_request"` + + - `McpApprovalResponse object { id, approval_request_id, approve, 2 more }` - The command to run. + A response to an MCP approval request. - - `env: map[string]` + - `id: string` - Environment variables to set for the command. + The unique ID of the approval response - - `type: "exec"` + - `approval_request_id: string` - The type of the local shell action. Always `exec`. + The ID of the approval request being answered. - - `"exec"` + - `approve: boolean` - - `timeout_ms: optional number` + Whether the request was approved. - Optional timeout in milliseconds for the command. + - `type: "mcp_approval_response"` - - `user: optional string` + The type of the item. Always `mcp_approval_response`. - Optional user to run the command as. + - `"mcp_approval_response"` - - `working_directory: optional string` + - `reason: optional string` - Optional working directory to run the command in. + Optional reason for the decision. - - `call_id: string` + - `McpCall object { id, arguments, name, 6 more }` - The unique ID of the local shell tool call generated by the model. + An invocation of a tool on an MCP server. - - `status: "in_progress" or "completed" or "incomplete"` + - `id: string` - The status of the local shell call. + The unique ID of the tool call. - - `"in_progress"` + - `arguments: string` - - `"completed"` + A JSON string of the arguments passed to the tool. - - `"incomplete"` + - `name: string` - - `type: "local_shell_call"` + The name of the tool that was run. - The type of the local shell call. Always `local_shell_call`. + - `server_label: string` - - `"local_shell_call"` + The label of the MCP server running the tool. - - `LocalShellCallOutput object { id, output, type, status }` + - `type: "mcp_call"` - The output of a local shell tool call. + The type of the item. Always `mcp_call`. - - `id: string` + - `"mcp_call"` - The unique ID of the local shell tool call generated by the model. + - `approval_request_id: optional string` - - `output: string` + Unique identifier for the MCP tool call approval request. + Include this value in a subsequent `mcp_approval_response` input to approve or reject the corresponding tool call. - A JSON string of the output of the local shell tool call. + - `error: optional string` - - `type: "local_shell_call_output"` + The error from the tool call, if any. - The type of the local shell tool call output. Always `local_shell_call_output`. + - `output: optional string` - - `"local_shell_call_output"` + The output from the tool call. - - `status: optional "in_progress" or "completed" or "incomplete"` + - `status: optional "in_progress" or "completed" or "incomplete" or 2 more` - The status of the item. One of `in_progress`, `completed`, or `incomplete`. + The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. - `"in_progress"` @@ -5956,1166 +11384,1286 @@ Create items in a conversation with the given ID. - `"incomplete"` - - `ShellCall object { action, call_id, type, 3 more }` + - `"calling"` - A tool representing a request to execute one or more shell commands. + - `"failed"` - - `action: object { commands, max_output_length, timeout_ms }` + - `CustomToolCall object { call_id, input, name, 3 more }` - The shell commands and limits that describe how to run the tool call. + A call to a custom tool created by the model. - - `commands: array of string` + - `call_id: string` - Ordered shell commands for the execution environment to run. + An identifier used to map this custom tool call to a tool call output. - - `max_output_length: optional number` + - `input: string` - Maximum number of UTF-8 characters to capture from combined stdout and stderr output. + The input for the custom tool call generated by the model. - - `timeout_ms: optional number` + - `name: string` - Maximum wall-clock time in milliseconds to allow the shell commands to run. + The name of the custom tool being called. - - `call_id: string` + - `type: "custom_tool_call"` - The unique ID of the shell tool call generated by the model. + The type of the custom tool call. Always `custom_tool_call`. - - `type: "shell_call"` + - `"custom_tool_call"` - The type of the item. Always `shell_call`. + - `id: optional string` - - `"shell_call"` + The unique ID of the custom tool call in the OpenAI platform. - - `id: optional string` + - `namespace: optional string` - The unique ID of the shell tool call. Populated when this item is returned via API. + The namespace of the custom tool being called. - - `environment: optional LocalEnvironment or ContainerReference` + - `CustomToolCallOutput object { call_id, output, type, id }` - The environment to execute the shell commands in. + The output of a custom tool call from your code, being sent back to the model. - - `LocalEnvironment object { type, skills }` + - `call_id: string` - - `ContainerReference object { container_id, type }` + The call ID, used to map this custom tool call output to a custom tool call. - - `status: optional "in_progress" or "completed" or "incomplete"` + - `output: string or array of ResponseInputText or ResponseInputImage or ResponseInputFile` - The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. + The output from the custom tool call generated by your code. + Can be a string or an list of output content. - - `"in_progress"` + - `StringOutput = string` - - `"completed"` + A string of the output of the custom tool call. - - `"incomplete"` + - `OutputContentList = array of ResponseInputText or ResponseInputImage or ResponseInputFile` - - `ShellCallOutput object { call_id, output, type, 3 more }` + Text, image, or file output of the custom tool call. - The streamed output items emitted by a shell tool call. + - `ResponseInputText object { text, type }` - - `call_id: string` + A text input to the model. - The unique ID of the shell tool call generated by the model. + - `ResponseInputImage object { detail, type, file_id, image_url }` - - `output: array of ResponseFunctionShellCallOutputContent` + An image input to the model. Learn about [image inputs](/docs/guides/vision). - Captured chunks of stdout and stderr output, along with their associated outcomes. + - `ResponseInputFile object { type, detail, file_data, 3 more }` - - `outcome: object { type } or object { exit_code, type }` + A file input to the model. - The exit or timeout outcome associated with this shell call. + - `type: "custom_tool_call_output"` - - `Timeout object { type }` + The type of the custom tool call output. Always `custom_tool_call_output`. - Indicates that the shell call exceeded its configured time limit. + - `"custom_tool_call_output"` - - `type: "timeout"` + - `id: optional string` - The outcome type. Always `timeout`. + The unique ID of the custom tool call output in the OpenAI platform. - - `"timeout"` + - `first_id: string` - - `Exit object { exit_code, type }` + The ID of the first item in the list. - Indicates that the shell commands finished and returned an exit code. + - `has_more: boolean` - - `exit_code: number` + Whether there are more items available. - The exit code returned by the shell process. + - `last_id: string` - - `type: "exit"` + The ID of the last item in the list. - The outcome type. Always `exit`. + - `object: "list"` - - `"exit"` + The type of object returned, must be `list`. - - `stderr: string` + - `"list"` - Captured stderr output for the shell call. +### Example - - `stdout: string` +```http +curl https://api.openai.com/v1/conversations/$CONVERSATION_ID/items \ + -H 'Content-Type: application/json' \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -d '{ + "items": [ + { + "content": "string", + "role": "user", + "type": "message" + } + ] + }' +``` - Captured stdout output for the shell call. +#### Response - - `type: "shell_call_output"` +```json +{ + "data": [ + { + "id": "id", + "content": [ + { + "text": "text", + "type": "input_text" + } + ], + "role": "unknown", + "status": "in_progress", + "type": "message", + "phase": "commentary" + } + ], + "first_id": "first_id", + "has_more": true, + "last_id": "last_id", + "object": "list" +} +``` - The type of the item. Always `shell_call_output`. +### Example - - `"shell_call_output"` +```http +curl https://api.openai.com/v1/conversations/conv_123/items \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -d '{ + "items": [ + { + "type": "message", + "role": "user", + "content": [ + {"type": "input_text", "text": "Hello!"} + ] + }, + { + "type": "message", + "role": "user", + "content": [ + {"type": "input_text", "text": "How are you?"} + ] + } + ] + }' +``` + +#### Response + +```json +{ + "object": "list", + "data": [ + { + "type": "message", + "id": "msg_abc", + "status": "completed", + "role": "user", + "content": [ + {"type": "input_text", "text": "Hello!"} + ] + }, + { + "type": "message", + "id": "msg_def", + "status": "completed", + "role": "user", + "content": [ + {"type": "input_text", "text": "How are you?"} + ] + } + ], + "first_id": "msg_abc", + "last_id": "msg_def", + "has_more": false +} +``` - - `id: optional string` +## List items - The unique ID of the shell tool call output. Populated when this item is returned via API. +**get** `/conversations/{conversation_id}/items` - - `max_output_length: optional number` +List all items for a conversation with the given ID. - The maximum number of UTF-8 characters captured for this shell call's combined output. +### Path Parameters - - `status: optional "in_progress" or "completed" or "incomplete"` +- `conversation_id: string` - The status of the shell call output. +### Query Parameters - - `"in_progress"` +- `after: optional string` - - `"completed"` + An item ID to list items after, used in pagination. - - `"incomplete"` +- `include: optional array of ResponseIncludable` - - `ApplyPatchCall object { call_id, operation, status, 2 more }` + Specify additional output data to include in the model response. Currently supported values are: - A tool call representing a request to create, delete, or update files using diff patches. + - `web_search_call.action.sources`: Include the sources of the web search tool call. + - `code_interpreter_call.outputs`: Includes the outputs of python code execution in code interpreter tool call items. + - `computer_call_output.output.image_url`: Include image urls from the computer call output. + - `file_search_call.results`: Include the search results of the file search tool call. + - `message.input_image.image_url`: Include image urls from the input message. + - `message.output_text.logprobs`: Include logprobs with assistant messages. + - `reasoning.encrypted_content`: Includes an encrypted version of reasoning tokens in reasoning item outputs. This enables reasoning items to be used in multi-turn conversations when using the Responses API statelessly (like when the `store` parameter is set to `false`, or when an organization is enrolled in the zero data retention program). - - `call_id: string` + - `"file_search_call.results"` - The unique ID of the apply patch tool call generated by the model. + - `"web_search_call.results"` - - `operation: object { diff, path, type } or object { path, type } or object { diff, path, type }` + - `"web_search_call.action.sources"` - The specific create, delete, or update instruction for the apply_patch tool call. + - `"message.input_image.image_url"` - - `CreateFile object { diff, path, type }` + - `"computer_call_output.output.image_url"` - Instruction for creating a new file via the apply_patch tool. + - `"code_interpreter_call.outputs"` - - `diff: string` + - `"reasoning.encrypted_content"` - Unified diff content to apply when creating the file. + - `"message.output_text.logprobs"` - - `path: string` +- `limit: optional number` - Path of the file to create relative to the workspace root. + A limit on the number of objects to be returned. Limit can range between + 1 and 100, and the default is 20. - - `type: "create_file"` +- `order: optional "asc" or "desc"` - The operation type. Always `create_file`. + The order to return the input items in. Default is `desc`. - - `"create_file"` + - `asc`: Return the input items in ascending order. + - `desc`: Return the input items in descending order. - - `DeleteFile object { path, type }` + - `"asc"` - Instruction for deleting an existing file via the apply_patch tool. + - `"desc"` - - `path: string` +### Returns - Path of the file to delete relative to the workspace root. +- `ConversationItemList object { data, first_id, has_more, 2 more }` - - `type: "delete_file"` + A list of Conversation items. - The operation type. Always `delete_file`. + - `data: array of ConversationItem` - - `"delete_file"` + A list of conversation items. - - `UpdateFile object { diff, path, type }` + - `Message object { id, content, role, 3 more }` - Instruction for updating an existing file via the apply_patch tool. + A message to or from the model. - - `diff: string` + - `id: string` - Unified diff content to apply to the existing file. + The unique ID of the message. - - `path: string` + - `content: array of ResponseInputText or ResponseOutputText or TextContent or 6 more` - Path of the file to update relative to the workspace root. + The content of the message - - `type: "update_file"` + - `ResponseInputText object { text, type }` - The operation type. Always `update_file`. + A text input to the model. - - `"update_file"` + - `text: string` - - `status: "in_progress" or "completed"` + The text input to the model. - The status of the apply patch tool call. One of `in_progress` or `completed`. + - `type: "input_text"` - - `"in_progress"` + The type of the input item. Always `input_text`. - - `"completed"` + - `"input_text"` - - `type: "apply_patch_call"` + - `ResponseOutputText object { annotations, logprobs, text, type }` - The type of the item. Always `apply_patch_call`. + A text output from the model. - - `"apply_patch_call"` + - `annotations: array of object { file_id, filename, index, type } or object { end_index, start_index, title, 2 more } or object { container_id, end_index, file_id, 3 more } or object { file_id, index, type }` - - `id: optional string` + The annotations of the text output. - The unique ID of the apply patch tool call. Populated when this item is returned via API. + - `FileCitation object { file_id, filename, index, type }` - - `ApplyPatchCallOutput object { call_id, status, type, 2 more }` + A citation to a file. - The streamed output emitted by an apply patch tool call. + - `file_id: string` - - `call_id: string` + The ID of the file. - The unique ID of the apply patch tool call generated by the model. + - `filename: string` - - `status: "completed" or "failed"` + The filename of the file cited. - The status of the apply patch tool call output. One of `completed` or `failed`. + - `index: number` - - `"completed"` + The index of the file in the list of files. - - `"failed"` + - `type: "file_citation"` - - `type: "apply_patch_call_output"` + The type of the file citation. Always `file_citation`. - The type of the item. Always `apply_patch_call_output`. + - `"file_citation"` - - `"apply_patch_call_output"` + - `URLCitation object { end_index, start_index, title, 2 more }` - - `id: optional string` + A citation for a web resource used to generate a model response. - The unique ID of the apply patch tool call output. Populated when this item is returned via API. + - `end_index: number` - - `output: optional string` + The index of the last character of the URL citation in the message. - Optional human-readable log text from the apply patch tool (e.g., patch results or errors). + - `start_index: number` - - `McpListTools object { id, server_label, tools, 2 more }` + The index of the first character of the URL citation in the message. - A list of tools available on an MCP server. + - `title: string` - - `id: string` + The title of the web resource. - The unique ID of the list. + - `type: "url_citation"` - - `server_label: string` + The type of the URL citation. Always `url_citation`. - The label of the MCP server. + - `"url_citation"` - - `tools: array of object { input_schema, name, annotations, description }` + - `url: string` - The tools available on the server. + The URL of the web resource. - - `input_schema: unknown` + - `ContainerFileCitation object { container_id, end_index, file_id, 3 more }` - The JSON schema describing the tool's input. + A citation for a container file used to generate a model response. - - `name: string` + - `container_id: string` - The name of the tool. + The ID of the container file. - - `annotations: optional unknown` + - `end_index: number` - Additional annotations about the tool. + The index of the last character of the container file citation in the message. - - `description: optional string` + - `file_id: string` - The description of the tool. + The ID of the file. - - `type: "mcp_list_tools"` + - `filename: string` - The type of the item. Always `mcp_list_tools`. + The filename of the container file cited. - - `"mcp_list_tools"` + - `start_index: number` - - `error: optional string` + The index of the first character of the container file citation in the message. - Error message if the server could not list tools. + - `type: "container_file_citation"` - - `McpApprovalRequest object { id, arguments, name, 2 more }` + The type of the container file citation. Always `container_file_citation`. - A request for human approval of a tool invocation. + - `"container_file_citation"` - - `id: string` + - `FilePath object { file_id, index, type }` - The unique ID of the approval request. + A path to a file. - - `arguments: string` + - `file_id: string` - A JSON string of arguments for the tool. + The ID of the file. - - `name: string` + - `index: number` - The name of the tool to run. + The index of the file in the list of files. - - `server_label: string` + - `type: "file_path"` - The label of the MCP server making the request. + The type of the file path. Always `file_path`. - - `type: "mcp_approval_request"` + - `"file_path"` - The type of the item. Always `mcp_approval_request`. + - `logprobs: array of object { token, bytes, logprob, top_logprobs }` - - `"mcp_approval_request"` + - `token: string` - - `McpApprovalResponse object { approval_request_id, approve, type, 2 more }` + - `bytes: array of number` - A response to an MCP approval request. + - `logprob: number` - - `approval_request_id: string` + - `top_logprobs: array of object { token, bytes, logprob }` - The ID of the approval request being answered. + - `token: string` - - `approve: boolean` + - `bytes: array of number` - Whether the request was approved. + - `logprob: number` - - `type: "mcp_approval_response"` + - `text: string` - The type of the item. Always `mcp_approval_response`. + The text output from the model. - - `"mcp_approval_response"` + - `type: "output_text"` - - `id: optional string` + The type of the output text. Always `output_text`. - The unique ID of the approval response + - `"output_text"` - - `reason: optional string` + - `TextContent object { text, type }` - Optional reason for the decision. + A text content. - - `McpCall object { id, arguments, name, 6 more }` + - `text: string` - An invocation of a tool on an MCP server. + - `type: "text"` - - `id: string` + - `"text"` - The unique ID of the tool call. + - `SummaryTextContent object { text, type }` - - `arguments: string` + A summary text from the model. - A JSON string of the arguments passed to the tool. + - `text: string` - - `name: string` + A summary of the reasoning output from the model so far. - The name of the tool that was run. + - `type: "summary_text"` - - `server_label: string` + The type of the object. Always `summary_text`. - The label of the MCP server running the tool. + - `"summary_text"` - - `type: "mcp_call"` + - `ReasoningText object { text, type }` - The type of the item. Always `mcp_call`. + Reasoning text from the model. - - `"mcp_call"` + - `text: string` - - `approval_request_id: optional string` + The reasoning text from the model. - Unique identifier for the MCP tool call approval request. - Include this value in a subsequent `mcp_approval_response` input to approve or reject the corresponding tool call. + - `type: "reasoning_text"` - - `error: optional string` + The type of the reasoning text. Always `reasoning_text`. - The error from the tool call, if any. + - `"reasoning_text"` - - `output: optional string` + - `ResponseOutputRefusal object { refusal, type }` - The output from the tool call. + A refusal from the model. - - `status: optional "in_progress" or "completed" or "incomplete" or 2 more` + - `refusal: string` - The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. + The refusal explanation from the model. - - `"in_progress"` + - `type: "refusal"` - - `"completed"` + The type of the refusal. Always `refusal`. - - `"incomplete"` + - `"refusal"` - - `"calling"` + - `ResponseInputImage object { detail, type, file_id, image_url }` - - `"failed"` + An image input to the model. Learn about [image inputs](/docs/guides/vision). - - `CustomToolCallOutput object { call_id, output, type, id }` + - `detail: "low" or "high" or "auto" or "original"` - The output of a custom tool call from your code, being sent back to the model. + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - - `call_id: string` + - `"low"` - The call ID, used to map this custom tool call output to a custom tool call. + - `"high"` - - `output: string or array of ResponseInputText or ResponseInputImage or ResponseInputFile` + - `"auto"` - The output from the custom tool call generated by your code. - Can be a string or an list of output content. + - `"original"` - - `StringOutput = string` + - `type: "input_image"` - A string of the output of the custom tool call. + The type of the input item. Always `input_image`. - - `OutputContentList = array of ResponseInputText or ResponseInputImage or ResponseInputFile` + - `"input_image"` - Text, image, or file output of the custom tool call. + - `file_id: optional string` - - `ResponseInputText object { text, type }` + The ID of the file to be sent to the model. - A text input to the model. + - `image_url: optional string` - - `ResponseInputImage object { detail, type, file_id, image_url }` + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - An image input to the model. Learn about [image inputs](/docs/guides/vision). + - `ComputerScreenshotContent object { detail, file_id, image_url, type }` - - `ResponseInputFile object { type, detail, file_data, 3 more }` + A screenshot of a computer. - A file input to the model. + - `detail: "low" or "high" or "auto" or "original"` - - `type: "custom_tool_call_output"` + The detail level of the screenshot image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - The type of the custom tool call output. Always `custom_tool_call_output`. + - `"low"` - - `"custom_tool_call_output"` + - `"high"` - - `id: optional string` + - `"auto"` - The unique ID of the custom tool call output in the OpenAI platform. + - `"original"` - - `CustomToolCall object { call_id, input, name, 3 more }` + - `file_id: string` - A call to a custom tool created by the model. + The identifier of an uploaded file that contains the screenshot. - - `call_id: string` + - `image_url: string` - An identifier used to map this custom tool call to a tool call output. + The URL of the screenshot image. - - `input: string` + - `type: "computer_screenshot"` - The input for the custom tool call generated by the model. + Specifies the event type. For a computer screenshot, this property is always set to `computer_screenshot`. - - `name: string` + - `"computer_screenshot"` - The name of the custom tool being called. + - `ResponseInputFile object { type, detail, file_data, 3 more }` - - `type: "custom_tool_call"` + A file input to the model. - The type of the custom tool call. Always `custom_tool_call`. + - `type: "input_file"` - - `"custom_tool_call"` + The type of the input item. Always `input_file`. - - `id: optional string` + - `"input_file"` - The unique ID of the custom tool call in the OpenAI platform. + - `detail: optional "low" or "high"` - - `namespace: optional string` + 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 namespace of the custom tool being called. + - `"low"` - - `CompactionTrigger object { type }` + - `"high"` - Compacts the current context. Must be the final input item. + - `file_data: optional string` - - `type: "compaction_trigger"` + The content of the file to be sent to the model. - The type of the item. Always `compaction_trigger`. + - `file_id: optional string` - - `"compaction_trigger"` + The ID of the file to be sent to the model. - - `ItemReference object { id, type }` + - `file_url: optional string` - An internal identifier for an item to reference. + The URL of the file to be sent to the model. - - `id: string` + - `filename: optional string` - The ID of the item to reference. + The name of the file to be sent to the model. - - `type: optional "item_reference"` + - `role: "unknown" or "user" or "assistant" or 5 more` - The type of item to reference. Always `item_reference`. + The role of the message. One of `unknown`, `user`, `assistant`, `system`, `critic`, `discriminator`, `developer`, or `tool`. - - `"item_reference"` + - `"unknown"` -### Returns + - `"user"` -- `ConversationItemList object { data, first_id, has_more, 2 more }` + - `"assistant"` - A list of Conversation items. + - `"system"` - - `data: array of ConversationItem` + - `"critic"` - A list of conversation items. + - `"discriminator"` - - `Message object { id, content, role, 3 more }` + - `"developer"` - A message to or from the model. + - `"tool"` - - `id: string` + - `status: "in_progress" or "completed" or "incomplete"` - The unique ID of the message. + The status of item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. - - `content: array of ResponseInputText or ResponseOutputText or TextContent or 6 more` + - `"in_progress"` - The content of the message + - `"completed"` - - `ResponseInputText object { text, type }` + - `"incomplete"` - A text input to the model. + - `type: "message"` - - `text: string` + The type of the message. Always set to `message`. - The text input to the model. + - `"message"` - - `type: "input_text"` + - `phase: optional "commentary" or "final_answer"` - The type of the input item. Always `input_text`. + Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend phase on all assistant messages — dropping it can degrade performance. Not used for user messages. - - `"input_text"` + - `"commentary"` - - `ResponseOutputText object { annotations, logprobs, text, type }` + - `"final_answer"` - A text output from the model. + - `FunctionCall object { id, arguments, call_id, 5 more }` - - `annotations: array of object { file_id, filename, index, type } or object { end_index, start_index, title, 2 more } or object { container_id, end_index, file_id, 3 more } or object { file_id, index, type }` + - `id: string` - The annotations of the text output. + The unique ID of the function tool call. - - `FileCitation object { file_id, filename, index, type }` + - `arguments: string` - A citation to a file. + A JSON string of the arguments to pass to the function. - - `file_id: string` + - `call_id: string` - The ID of the file. + The unique ID of the function tool call generated by the model. - - `filename: string` + - `name: string` - The filename of the file cited. + The name of the function to run. - - `index: number` + - `status: "in_progress" or "completed" or "incomplete"` - The index of the file in the list of files. + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `type: "file_citation"` + - `"in_progress"` - The type of the file citation. Always `file_citation`. + - `"completed"` - - `"file_citation"` + - `"incomplete"` - - `URLCitation object { end_index, start_index, title, 2 more }` + - `type: "function_call"` - A citation for a web resource used to generate a model response. + The type of the function tool call. Always `function_call`. - - `end_index: number` + - `"function_call"` - The index of the last character of the URL citation in the message. + - `created_by: optional string` - - `start_index: number` + The identifier of the actor that created the item. - The index of the first character of the URL citation in the message. + - `namespace: optional string` - - `title: string` + The namespace of the function to run. - The title of the web resource. + - `FunctionCallOutput object { id, call_id, output, 3 more }` - - `type: "url_citation"` + - `id: string` - The type of the URL citation. Always `url_citation`. + The unique ID of the function call tool output. - - `"url_citation"` + - `call_id: string` - - `url: string` + The unique ID of the function tool call generated by the model. - The URL of the web resource. + - `output: string or array of ResponseInputText or ResponseInputImage or ResponseInputFile` - - `ContainerFileCitation object { container_id, end_index, file_id, 3 more }` + The output from the function call generated by your code. + Can be a string or an list of output content. - A citation for a container file used to generate a model response. + - `StringOutput = string` - - `container_id: string` + A string of the output of the function call. - The ID of the container file. + - `OutputContentList = array of ResponseInputText or ResponseInputImage or ResponseInputFile` - - `end_index: number` + Text, image, or file output of the function call. - The index of the last character of the container file citation in the message. + - `ResponseInputText object { text, type }` - - `file_id: string` + A text input to the model. - The ID of the file. + - `ResponseInputImage object { detail, type, file_id, image_url }` - - `filename: string` + An image input to the model. Learn about [image inputs](/docs/guides/vision). - The filename of the container file cited. + - `ResponseInputFile object { type, detail, file_data, 3 more }` - - `start_index: number` + A file input to the model. - The index of the first character of the container file citation in the message. + - `status: "in_progress" or "completed" or "incomplete"` - - `type: "container_file_citation"` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - The type of the container file citation. Always `container_file_citation`. + - `"in_progress"` - - `"container_file_citation"` + - `"completed"` - - `FilePath object { file_id, index, type }` + - `"incomplete"` - A path to a file. + - `type: "function_call_output"` - - `file_id: string` + The type of the function tool call output. Always `function_call_output`. - The ID of the file. + - `"function_call_output"` - - `index: number` + - `created_by: optional string` - The index of the file in the list of files. + The identifier of the actor that created the item. - - `type: "file_path"` + - `FileSearchCall object { id, queries, status, 2 more }` - The type of the file path. Always `file_path`. + The results of a file search tool call. See the + [file search guide](/docs/guides/tools-file-search) for more information. - - `"file_path"` + - `id: string` - - `logprobs: array of object { token, bytes, logprob, top_logprobs }` + The unique ID of the file search tool call. - - `token: string` + - `queries: array of string` - - `bytes: array of number` + The queries used to search for files. - - `logprob: number` + - `status: "in_progress" or "searching" or "completed" or 2 more` - - `top_logprobs: array of object { token, bytes, logprob }` + The status of the file search tool call. One of `in_progress`, + `searching`, `incomplete` or `failed`, - - `token: string` + - `"in_progress"` - - `bytes: array of number` + - `"searching"` - - `logprob: number` + - `"completed"` - - `text: string` + - `"incomplete"` - The text output from the model. + - `"failed"` - - `type: "output_text"` + - `type: "file_search_call"` - The type of the output text. Always `output_text`. + The type of the file search tool call. Always `file_search_call`. - - `"output_text"` + - `"file_search_call"` - - `TextContent object { text, type }` + - `results: optional array of object { attributes, file_id, filename, 2 more }` - A text content. + The results of the file search tool call. - - `text: string` + - `attributes: optional map[string or number or boolean]` - - `type: "text"` + Set of 16 key-value pairs that can be attached to an object. This can be + useful for storing additional information about the object in a structured + format, and querying for objects via API or the dashboard. Keys are strings + with a maximum length of 64 characters. Values are strings with a maximum + length of 512 characters, booleans, or numbers. - - `"text"` + - `string` - - `SummaryTextContent object { text, type }` + - `number` - A summary text from the model. + - `boolean` - - `text: string` + - `file_id: optional string` - A summary of the reasoning output from the model so far. + The unique ID of the file. - - `type: "summary_text"` + - `filename: optional string` - The type of the object. Always `summary_text`. + The name of the file. - - `"summary_text"` + - `score: optional number` - - `ReasoningText object { text, type }` + The relevance score of the file - a value between 0 and 1. - Reasoning text from the model. + - `text: optional string` - - `text: string` + The text that was retrieved from the file. - The reasoning text from the model. + - `WebSearchCall object { id, action, status, type }` - - `type: "reasoning_text"` + The results of a web search tool call. See the + [web search guide](/docs/guides/tools-web-search) for more information. - The type of the reasoning text. Always `reasoning_text`. + - `id: string` - - `"reasoning_text"` + The unique ID of the web search tool call. - - `ResponseOutputRefusal object { refusal, type }` + - `action: object { type, queries, query, sources } or object { type, url } or object { pattern, type, url }` - A refusal from the model. + An object describing the specific action taken in this web search call. + Includes details on how the model used the web (search, open_page, find_in_page). - - `refusal: string` + - `Search object { type, queries, query, sources }` - The refusal explanation from the model. + Action type "search" - Performs a web search query. - - `type: "refusal"` + - `type: "search"` - The type of the refusal. Always `refusal`. + The action type. - - `"refusal"` + - `"search"` - - `ResponseInputImage object { detail, type, file_id, image_url }` + - `queries: optional array of string` - An image input to the model. Learn about [image inputs](/docs/guides/vision). + The search queries. - - `detail: "low" or "high" or "auto" or "original"` + - `query: optional string` - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + The search query. - - `"low"` + - `sources: optional array of object { type, url }` - - `"high"` + The sources used in the search. - - `"auto"` + - `type: "url"` - - `"original"` + The type of source. Always `url`. - - `type: "input_image"` + - `"url"` - The type of the input item. Always `input_image`. + - `url: string` - - `"input_image"` + The URL of the source. - - `file_id: optional string` + - `OpenPage object { type, url }` - The ID of the file to be sent to the model. + Action type "open_page" - Opens a specific URL from search results. - - `image_url: optional string` + - `type: "open_page"` - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + The action type. - - `ComputerScreenshotContent object { detail, file_id, image_url, type }` + - `"open_page"` - A screenshot of a computer. + - `url: optional string` - - `detail: "low" or "high" or "auto" or "original"` + The URL opened by the model. - The detail level of the screenshot image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + - `FindInPage object { pattern, type, url }` - - `"low"` + Action type "find_in_page": Searches for a pattern within a loaded page. - - `"high"` + - `pattern: string` - - `"auto"` + The pattern or text to search for within the page. - - `"original"` + - `type: "find_in_page"` - - `file_id: string` + The action type. - The identifier of an uploaded file that contains the screenshot. + - `"find_in_page"` - - `image_url: string` + - `url: string` - The URL of the screenshot image. + The URL of the page searched for the pattern. - - `type: "computer_screenshot"` + - `status: "in_progress" or "searching" or "completed" or "failed"` - Specifies the event type. For a computer screenshot, this property is always set to `computer_screenshot`. + The status of the web search tool call. - - `"computer_screenshot"` + - `"in_progress"` - - `ResponseInputFile object { type, detail, file_data, 3 more }` + - `"searching"` - A file input to the model. + - `"completed"` - - `type: "input_file"` + - `"failed"` - The type of the input item. Always `input_file`. + - `type: "web_search_call"` - - `"input_file"` + The type of the web search tool call. Always `web_search_call`. - - `detail: optional "low" or "high"` + - `"web_search_call"` - The detail level of the file to be sent to the model. Use `low` for the default rendering behavior, or `high` to render the file at higher quality. Defaults to `low`. + - `ImageGenerationCall object { id, result, status, type }` - - `"low"` + An image generation request made by the model. - - `"high"` + - `id: string` - - `file_data: optional string` + The unique ID of the image generation call. - The content of the file to be sent to the model. + - `result: string` - - `file_id: optional string` + The generated image encoded in base64. - The ID of the file to be sent to the model. + - `status: "in_progress" or "completed" or "generating" or "failed"` - - `file_url: optional string` + The status of the image generation call. - The URL of the file to be sent to the model. + - `"in_progress"` - - `filename: optional string` + - `"completed"` - The name of the file to be sent to the model. + - `"generating"` - - `role: "unknown" or "user" or "assistant" or 5 more` + - `"failed"` - The role of the message. One of `unknown`, `user`, `assistant`, `system`, `critic`, `discriminator`, `developer`, or `tool`. + - `type: "image_generation_call"` - - `"unknown"` + The type of the image generation call. Always `image_generation_call`. - - `"user"` + - `"image_generation_call"` - - `"assistant"` + - `ComputerCall object { id, call_id, pending_safety_checks, 4 more }` - - `"system"` + A tool call to a computer use tool. See the + [computer use guide](/docs/guides/tools-computer-use) for more information. - - `"critic"` + - `id: string` - - `"discriminator"` + The unique ID of the computer call. - - `"developer"` + - `call_id: string` - - `"tool"` + An identifier used when responding to the tool call with output. - - `status: "in_progress" or "completed" or "incomplete"` + - `pending_safety_checks: array of object { id, code, message }` - The status of item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. + The pending safety checks for the computer call. - - `"in_progress"` + - `id: string` - - `"completed"` + The ID of the pending safety check. - - `"incomplete"` + - `code: optional string` - - `type: "message"` + The type of the pending safety check. - The type of the message. Always set to `message`. + - `message: optional string` - - `"message"` + Details about the pending safety check. - - `phase: optional "commentary" or "final_answer"` + - `status: "in_progress" or "completed" or "incomplete"` - Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend phase on all assistant messages — dropping it can degrade performance. Not used for user messages. + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `"commentary"` + - `"in_progress"` - - `"final_answer"` + - `"completed"` - - `FunctionCall object { id, arguments, call_id, 5 more }` + - `"incomplete"` - - `id: string` + - `type: "computer_call"` - The unique ID of the function tool call. + The type of the computer call. Always `computer_call`. - - `arguments: string` + - `"computer_call"` - A JSON string of the arguments to pass to the function. + - `action: optional ComputerAction` - - `call_id: string` + A click action. - The unique ID of the function tool call generated by the model. + - `Click object { button, type, x, 2 more }` - - `name: string` + A click action. - The name of the function to run. + - `button: "left" or "right" or "wheel" or 2 more` - - `status: "in_progress" or "completed" or "incomplete"` + Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `"left"` - - `"in_progress"` + - `"right"` - - `"completed"` + - `"wheel"` - - `"incomplete"` + - `"back"` - - `type: "function_call"` + - `"forward"` - The type of the function tool call. Always `function_call`. + - `type: "click"` - - `"function_call"` + Specifies the event type. For a click action, this property is always `click`. - - `created_by: optional string` + - `"click"` - The identifier of the actor that created the item. + - `x: number` - - `namespace: optional string` + The x-coordinate where the click occurred. - The namespace of the function to run. + - `y: number` - - `FunctionCallOutput object { id, call_id, output, 3 more }` + The y-coordinate where the click occurred. - - `id: string` + - `keys: optional array of string` - The unique ID of the function call tool output. + The keys being held while clicking. - - `call_id: string` + - `DoubleClick object { keys, type, x, y }` - The unique ID of the function tool call generated by the model. + A double click action. - - `output: string or array of ResponseInputText or ResponseInputImage or ResponseInputFile` + - `keys: array of string` - The output from the function call generated by your code. - Can be a string or an list of output content. + The keys being held while double-clicking. - - `StringOutput = string` + - `type: "double_click"` - A string of the output of the function call. + Specifies the event type. For a double click action, this property is always set to `double_click`. - - `OutputContentList = array of ResponseInputText or ResponseInputImage or ResponseInputFile` + - `"double_click"` - Text, image, or file output of the function call. + - `x: number` - - `ResponseInputText object { text, type }` + The x-coordinate where the double click occurred. - A text input to the model. + - `y: number` - - `ResponseInputImage object { detail, type, file_id, image_url }` + The y-coordinate where the double click occurred. - An image input to the model. Learn about [image inputs](/docs/guides/vision). + - `Drag object { path, type, keys }` - - `ResponseInputFile object { type, detail, file_data, 3 more }` + A drag action. - A file input to the model. + - `path: array of object { x, y }` - - `status: "in_progress" or "completed" or "incomplete"` + An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + ``` + [ + { x: 100, y: 200 }, + { x: 200, y: 300 } + ] + ``` - - `"in_progress"` + - `x: number` - - `"completed"` + The x-coordinate. - - `"incomplete"` + - `y: number` - - `type: "function_call_output"` + The y-coordinate. - The type of the function tool call output. Always `function_call_output`. + - `type: "drag"` - - `"function_call_output"` + Specifies the event type. For a drag action, this property is always set to `drag`. - - `created_by: optional string` + - `"drag"` - The identifier of the actor that created the item. + - `keys: optional array of string` - - `FileSearchCall object { id, queries, status, 2 more }` + The keys being held while dragging the mouse. - The results of a file search tool call. See the - [file search guide](/docs/guides/tools-file-search) for more information. + - `Keypress object { keys, type }` - - `id: string` + A collection of keypresses the model would like to perform. - The unique ID of the file search tool call. + - `keys: array of string` - - `queries: array of string` + The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. - The queries used to search for files. + - `type: "keypress"` - - `status: "in_progress" or "searching" or "completed" or 2 more` + Specifies the event type. For a keypress action, this property is always set to `keypress`. - The status of the file search tool call. One of `in_progress`, - `searching`, `incomplete` or `failed`, + - `"keypress"` - - `"in_progress"` + - `Move object { type, x, y, keys }` - - `"searching"` + A mouse move action. - - `"completed"` + - `type: "move"` - - `"incomplete"` + Specifies the event type. For a move action, this property is always set to `move`. - - `"failed"` + - `"move"` - - `type: "file_search_call"` + - `x: number` - The type of the file search tool call. Always `file_search_call`. + The x-coordinate to move to. - - `"file_search_call"` + - `y: number` - - `results: optional array of object { attributes, file_id, filename, 2 more }` + The y-coordinate to move to. - The results of the file search tool call. + - `keys: optional array of string` - - `attributes: optional map[string or number or boolean]` + The keys being held while moving the mouse. - Set of 16 key-value pairs that can be attached to an object. This can be - useful for storing additional information about the object in a structured - format, and querying for objects via API or the dashboard. Keys are strings - with a maximum length of 64 characters. Values are strings with a maximum - length of 512 characters, booleans, or numbers. + - `Screenshot object { type }` - - `string` + A screenshot action. - - `number` + - `type: "screenshot"` - - `boolean` + Specifies the event type. For a screenshot action, this property is always set to `screenshot`. - - `file_id: optional string` + - `"screenshot"` - The unique ID of the file. + - `Scroll object { scroll_x, scroll_y, type, 3 more }` - - `filename: optional string` + A scroll action. - The name of the file. + - `scroll_x: number` - - `score: optional number` + The horizontal scroll distance. - The relevance score of the file - a value between 0 and 1. + - `scroll_y: number` - - `text: optional string` + The vertical scroll distance. - The text that was retrieved from the file. + - `type: "scroll"` - - `WebSearchCall object { id, action, status, type }` + Specifies the event type. For a scroll action, this property is always set to `scroll`. - The results of a web search tool call. See the - [web search guide](/docs/guides/tools-web-search) for more information. + - `"scroll"` - - `id: string` + - `x: number` - The unique ID of the web search tool call. + The x-coordinate where the scroll occurred. - - `action: object { query, type, queries, sources } or object { type, url } or object { pattern, type, url }` + - `y: number` - An object describing the specific action taken in this web search call. - Includes details on how the model used the web (search, open_page, find_in_page). + The y-coordinate where the scroll occurred. - - `Search object { query, type, queries, sources }` + - `keys: optional array of string` - Action type "search" - Performs a web search query. + The keys being held while scrolling. - - `query: string` + - `Type object { text, type }` - [DEPRECATED] The search query. + An action to type in text. - - `type: "search"` + - `text: string` - The action type. + The text to type. - - `"search"` + - `type: "type"` - - `queries: optional array of string` + Specifies the event type. For a type action, this property is always set to `type`. - The search queries. + - `"type"` - - `sources: optional array of object { type, url }` + - `Wait object { type }` - The sources used in the search. + A wait action. - - `type: "url"` + - `type: "wait"` - The type of source. Always `url`. + Specifies the event type. For a wait action, this property is always set to `wait`. - - `"url"` + - `"wait"` - - `url: string` + - `actions: optional ComputerActionList` - The URL of the source. + Flattened batched actions for `computer_use`. Each action includes an + `type` discriminator and action-specific fields. - - `OpenPage object { type, url }` + - `Click object { button, type, x, 2 more }` - Action type "open_page" - Opens a specific URL from search results. + A click action. - - `type: "open_page"` + - `DoubleClick object { keys, type, x, y }` - The action type. + A double click action. - - `"open_page"` + - `Drag object { path, type, keys }` - - `url: optional string` + A drag action. - The URL opened by the model. + - `Keypress object { keys, type }` - - `FindInPage object { pattern, type, url }` + A collection of keypresses the model would like to perform. - Action type "find_in_page": Searches for a pattern within a loaded page. + - `Move object { type, x, y, keys }` - - `pattern: string` + A mouse move action. - The pattern or text to search for within the page. + - `Screenshot object { type }` - - `type: "find_in_page"` + A screenshot action. - The action type. + - `Scroll object { scroll_x, scroll_y, type, 3 more }` - - `"find_in_page"` + A scroll action. - - `url: string` + - `Type object { text, type }` - The URL of the page searched for the pattern. + An action to type in text. - - `status: "in_progress" or "searching" or "completed" or "failed"` + - `Wait object { type }` - The status of the web search tool call. + A wait action. - - `"in_progress"` + - `ComputerCallOutput object { id, call_id, output, 4 more }` - - `"searching"` + - `id: string` - - `"completed"` + The unique ID of the computer call tool output. - - `"failed"` + - `call_id: string` - - `type: "web_search_call"` + The ID of the computer tool call that produced the output. - The type of the web search tool call. Always `web_search_call`. + - `output: ResponseComputerToolCallOutputScreenshot` - - `"web_search_call"` + A computer screenshot image used with the computer use tool. - - `ImageGenerationCall object { id, result, status, type }` + - `type: "computer_screenshot"` - An image generation request made by the model. + Specifies the event type. For a computer screenshot, this property is + always set to `computer_screenshot`. - - `id: string` + - `"computer_screenshot"` - The unique ID of the image generation call. + - `file_id: optional string` - - `result: string` + The identifier of an uploaded file that contains the screenshot. - The generated image encoded in base64. + - `image_url: optional string` - - `status: "in_progress" or "completed" or "generating" or "failed"` + The URL of the screenshot image. - The status of the image generation call. + - `status: "completed" or "incomplete" or "failed" or "in_progress"` - - `"in_progress"` + The status of the message input. One of `in_progress`, `completed`, or + `incomplete`. Populated when input items are returned via API. - `"completed"` - - `"generating"` + - `"incomplete"` - `"failed"` - - `type: "image_generation_call"` + - `"in_progress"` - The type of the image generation call. Always `image_generation_call`. + - `type: "computer_call_output"` - - `"image_generation_call"` + The type of the computer tool call output. Always `computer_call_output`. - - `ComputerCall object { id, call_id, pending_safety_checks, 4 more }` + - `"computer_call_output"` - A tool call to a computer use tool. See the - [computer use guide](/docs/guides/tools-computer-use) for more information. + - `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 unique ID of the computer call. + The ID of the pending safety check. - - `call_id: string` + - `code: optional string` - An identifier used when responding to the tool call with output. + The type of the pending safety check. - - `pending_safety_checks: array of object { id, code, message }` + - `message: optional string` - The pending safety checks for the computer call. + Details about the pending safety check. + + - `created_by: optional string` + + The identifier of the actor that created the item. + + - `ToolSearchCall object { id, arguments, call_id, 4 more }` - `id: string` - The ID of the pending safety check. + The unique ID of the tool search call item. - - `code: optional string` + - `arguments: unknown` - The type of the pending safety check. + Arguments used for the tool search call. - - `message: optional string` + - `call_id: string` - Details about the pending safety check. + The unique ID of the tool search call generated by the model. + + - `execution: "server" or "client"` + + Whether tool search was executed by the server or by the client. + + - `"server"` + + - `"client"` - `status: "in_progress" or "completed" or "incomplete"` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + The status of the tool search call item that was recorded. - `"in_progress"` @@ -7123,615 +12671,632 @@ Create items in a conversation with the given ID. - `"incomplete"` - - `type: "computer_call"` - - The type of the computer call. Always `computer_call`. - - - `"computer_call"` - - - `action: optional ComputerAction` + - `type: "tool_search_call"` - A click action. + The type of the item. Always `tool_search_call`. - - `Click object { button, type, x, 2 more }` + - `"tool_search_call"` - A click action. + - `created_by: optional string` - - `button: "left" or "right" or "wheel" or 2 more` + The identifier of the actor that created the item. - Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. + - `ToolSearchOutput object { id, call_id, execution, 4 more }` - - `"left"` + - `id: string` - - `"right"` + The unique ID of the tool search output item. - - `"wheel"` + - `call_id: string` - - `"back"` + The unique ID of the tool search call generated by the model. - - `"forward"` + - `execution: "server" or "client"` - - `type: "click"` + Whether tool search was executed by the server or by the client. - Specifies the event type. For a click action, this property is always `click`. + - `"server"` - - `"click"` + - `"client"` - - `x: number` + - `status: "in_progress" or "completed" or "incomplete"` - The x-coordinate where the click occurred. + The status of the tool search output item that was recorded. - - `y: number` + - `"in_progress"` - The y-coordinate where the click occurred. + - `"completed"` - - `keys: optional array of string` + - `"incomplete"` - The keys being held while clicking. + - `tools: array of object { name, parameters, strict, 3 more } or object { type, vector_store_ids, filters, 2 more } or object { type } or 12 more` - - `DoubleClick object { keys, type, x, y }` + The loaded tool definitions returned by tool search. - A double click action. + - `Function object { name, parameters, strict, 3 more }` - - `keys: array of string` + 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). - The keys being held while double-clicking. + - `name: string` - - `type: "double_click"` + The name of the function to call. - Specifies the event type. For a double click action, this property is always set to `double_click`. + - `parameters: map[unknown]` - - `"double_click"` + A JSON schema object describing the parameters of the function. - - `x: number` + - `strict: boolean` - The x-coordinate where the double click occurred. + Whether to enforce strict parameter validation. Default `true`. - - `y: number` + - `type: "function"` - The y-coordinate where the double click occurred. + The type of the function tool. Always `function`. - - `Drag object { path, type, keys }` + - `"function"` - A drag action. + - `defer_loading: optional boolean` - - `path: array of object { x, y }` + Whether this function is deferred and loaded via tool search. - An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg + - `description: optional string` - ``` - [ - { x: 100, y: 200 }, - { x: 200, y: 300 } - ] - ``` + A description of the function. Used by the model to determine whether or not to call the function. - - `x: number` + - `FileSearch object { type, vector_store_ids, filters, 2 more }` - The x-coordinate. + 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). - - `y: number` + - `type: "file_search"` - The y-coordinate. + The type of the file search tool. Always `file_search`. - - `type: "drag"` + - `"file_search"` - Specifies the event type. For a drag action, this property is always set to `drag`. + - `vector_store_ids: array of string` - - `"drag"` + The IDs of the vector stores to search. - - `keys: optional array of string` + - `filters: optional ComparisonFilter or CompoundFilter` - The keys being held while dragging the mouse. + A filter to apply. - - `Keypress object { keys, type }` + - `ComparisonFilter object { key, type, value }` - A collection of keypresses the model would like to perform. + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - - `keys: array of string` + - `key: string` - The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. + The key to compare against the value. - - `type: "keypress"` + - `type: "eq" or "ne" or "gt" or 5 more` - Specifies the event type. For a keypress action, this property is always set to `keypress`. + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - - `"keypress"` + - `eq`: equals + - `ne`: not equal + - `gt`: greater than + - `gte`: greater than or equal + - `lt`: less than + - `lte`: less than or equal + - `in`: in + - `nin`: not in - - `Move object { type, x, y, keys }` + - `"eq"` - A mouse move action. + - `"ne"` - - `type: "move"` + - `"gt"` - Specifies the event type. For a move action, this property is always set to `move`. + - `"gte"` - - `"move"` + - `"lt"` - - `x: number` + - `"lte"` - The x-coordinate to move to. + - `"in"` - - `y: number` + - `"nin"` - The y-coordinate to move to. + - `value: string or number or boolean or array of string or number` - - `keys: optional array of string` + The value to compare against the attribute key; supports string, number, or boolean types. - The keys being held while moving the mouse. + - `string` - - `Screenshot object { type }` + - `number` - A screenshot action. + - `boolean` - - `type: "screenshot"` + - `array of string or number` - Specifies the event type. For a screenshot action, this property is always set to `screenshot`. + - `string` - - `"screenshot"` + - `number` - - `Scroll object { scroll_x, scroll_y, type, 3 more }` + - `CompoundFilter object { filters, type }` - A scroll action. + Combine multiple filters using `and` or `or`. - - `scroll_x: number` + - `filters: array of ComparisonFilter or unknown` - The horizontal scroll distance. + Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. - - `scroll_y: number` + - `ComparisonFilter object { key, type, value }` - The vertical scroll distance. + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - - `type: "scroll"` + - `unknown` - Specifies the event type. For a scroll action, this property is always set to `scroll`. + - `type: "and" or "or"` - - `"scroll"` + Type of operation: `and` or `or`. - - `x: number` + - `"and"` - The x-coordinate where the scroll occurred. + - `"or"` - - `y: number` + - `max_num_results: optional number` - The y-coordinate where the scroll occurred. + The maximum number of results to return. This number should be between 1 and 50 inclusive. - - `keys: optional array of string` + - `ranking_options: optional object { hybrid_search, ranker, score_threshold }` - The keys being held while scrolling. + Ranking options for search. - - `Type object { text, type }` + - `hybrid_search: optional object { embedding_weight, text_weight }` - An action to type in text. + Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. - - `text: string` + - `embedding_weight: number` - The text to type. + The weight of the embedding in the reciprocal ranking fusion. - - `type: "type"` + - `text_weight: number` - Specifies the event type. For a type action, this property is always set to `type`. + The weight of the text in the reciprocal ranking fusion. - - `"type"` + - `ranker: optional "auto" or "default-2024-11-15"` - - `Wait object { type }` + The ranker to use for the file search. - A wait action. + - `"auto"` - - `type: "wait"` + - `"default-2024-11-15"` - Specifies the event type. For a wait action, this property is always set to `wait`. + - `score_threshold: optional number` - - `"wait"` + The score threshold for the file search, a number between 0 and 1. Numbers closer to 1 will attempt to return only the most relevant results, but may return fewer results. - - `actions: optional ComputerActionList` + - `Computer object { type }` - Flattened batched actions for `computer_use`. Each action includes an - `type` discriminator and action-specific fields. + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `Click object { button, type, x, 2 more }` + - `type: "computer"` - A click action. + The type of the computer tool. Always `computer`. - - `DoubleClick object { keys, type, x, y }` + - `"computer"` - A double click action. + - `ComputerUsePreview object { display_height, display_width, environment, type }` - - `Drag object { path, type, keys }` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - A drag action. + - `display_height: number` - - `Keypress object { keys, type }` + The height of the computer display. - A collection of keypresses the model would like to perform. + - `display_width: number` - - `Move object { type, x, y, keys }` + The width of the computer display. - A mouse move action. + - `environment: "windows" or "mac" or "linux" or 2 more` - - `Screenshot object { type }` + The type of computer environment to control. - A screenshot action. + - `"windows"` - - `Scroll object { scroll_x, scroll_y, type, 3 more }` + - `"mac"` - A scroll action. + - `"linux"` - - `Type object { text, type }` + - `"ubuntu"` - An action to type in text. + - `"browser"` - - `Wait object { type }` + - `type: "computer_use_preview"` - A wait action. + The type of the computer use tool. Always `computer_use_preview`. - - `ComputerCallOutput object { id, call_id, output, 4 more }` + - `"computer_use_preview"` - - `id: string` + - `WebSearch object { type, filters, search_context_size, user_location }` - The unique ID of the computer call tool output. + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](/docs/guides/tools-web-search). - - `call_id: string` + - `type: "web_search" or "web_search_2025_08_26"` - The ID of the computer tool call that produced the output. + The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. - - `output: ResponseComputerToolCallOutputScreenshot` + - `"web_search"` - A computer screenshot image used with the computer use tool. + - `"web_search_2025_08_26"` - - `type: "computer_screenshot"` + - `filters: optional object { allowed_domains }` - Specifies the event type. For a computer screenshot, this property is - always set to `computer_screenshot`. + Filters for the search. - - `"computer_screenshot"` + - `allowed_domains: optional array of string` - - `file_id: optional string` + Allowed domains for the search. If not provided, all domains are allowed. + Subdomains of the provided domains are allowed as well. - The identifier of an uploaded file that contains the screenshot. + Example: `["pubmed.ncbi.nlm.nih.gov"]` - - `image_url: optional string` + - `search_context_size: optional "low" or "medium" or "high"` - The URL of the screenshot image. + High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. - - `status: "completed" or "incomplete" or "failed" or "in_progress"` + - `"low"` - The status of the message input. One of `in_progress`, `completed`, or - `incomplete`. Populated when input items are returned via API. + - `"medium"` - - `"completed"` + - `"high"` - - `"incomplete"` + - `user_location: optional object { city, country, region, 2 more }` - - `"failed"` + The approximate location of the user. - - `"in_progress"` + - `city: optional string` - - `type: "computer_call_output"` + Free text input for the city of the user, e.g. `San Francisco`. - The type of the computer tool call output. Always `computer_call_output`. + - `country: optional string` - - `"computer_call_output"` + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - - `acknowledged_safety_checks: optional array of object { id, code, message }` + - `region: optional string` - The safety checks reported by the API that have been acknowledged by the - developer. + Free text input for the region of the user, e.g. `California`. - - `id: string` + - `timezone: optional string` - The ID of the pending safety check. + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - - `code: optional string` + - `type: optional "approximate"` - The type of the pending safety check. + The type of location approximation. Always `approximate`. - - `message: optional string` + - `"approximate"` - Details about the pending safety check. + - `Mcp object { server_label, type, allowed_tools, 7 more }` - - `created_by: optional string` + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](/docs/guides/tools-remote-mcp). - The identifier of the actor that created the item. + - `server_label: string` - - `ToolSearchCall object { id, arguments, call_id, 4 more }` + A label for this MCP server, used to identify it in tool calls. - - `id: string` + - `type: "mcp"` - The unique ID of the tool search call item. + The type of the MCP tool. Always `mcp`. - - `arguments: unknown` + - `"mcp"` - Arguments used for the tool search call. + - `allowed_tools: optional array of string or object { read_only, tool_names }` - - `call_id: string` + List of allowed tool names or a filter object. - The unique ID of the tool search call generated by the model. + - `McpAllowedTools = array of string` - - `execution: "server" or "client"` + A string array of allowed tool names - Whether tool search was executed by the server or by the client. + - `McpToolFilter object { read_only, tool_names }` - - `"server"` + A filter object to specify which tools are allowed. - - `"client"` + - `read_only: optional boolean` - - `status: "in_progress" or "completed" or "incomplete"` + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. - The status of the tool search call item that was recorded. + - `tool_names: optional array of string` - - `"in_progress"` + List of allowed tool names. - - `"completed"` + - `authorization: optional string` - - `"incomplete"` + An OAuth access token that can be used with a remote MCP server, either + with a custom MCP server URL or a service connector. Your application + must handle the OAuth authorization flow and provide the token here. - - `type: "tool_search_call"` + - `connector_id: optional "connector_dropbox" or "connector_gmail" or "connector_googlecalendar" or 5 more` - The type of the item. Always `tool_search_call`. + Identifier for service connectors, like those available in ChatGPT. One of + `server_url` or `connector_id` must be provided. Learn more about service + connectors [here](/docs/guides/tools-remote-mcp#connectors). - - `"tool_search_call"` + Currently supported `connector_id` values are: - - `created_by: optional string` + - Dropbox: `connector_dropbox` + - Gmail: `connector_gmail` + - Google Calendar: `connector_googlecalendar` + - Google Drive: `connector_googledrive` + - Microsoft Teams: `connector_microsoftteams` + - Outlook Calendar: `connector_outlookcalendar` + - Outlook Email: `connector_outlookemail` + - SharePoint: `connector_sharepoint` - The identifier of the actor that created the item. + - `"connector_dropbox"` - - `ToolSearchOutput object { id, call_id, execution, 4 more }` + - `"connector_gmail"` - - `id: string` + - `"connector_googlecalendar"` - The unique ID of the tool search output item. + - `"connector_googledrive"` - - `call_id: string` + - `"connector_microsoftteams"` - The unique ID of the tool search call generated by the model. + - `"connector_outlookcalendar"` - - `execution: "server" or "client"` + - `"connector_outlookemail"` - Whether tool search was executed by the server or by the client. + - `"connector_sharepoint"` - - `"server"` + - `defer_loading: optional boolean` - - `"client"` + Whether this MCP tool is deferred and discovered via tool search. - - `status: "in_progress" or "completed" or "incomplete"` + - `headers: optional map[string]` - The status of the tool search output item that was recorded. + Optional HTTP headers to send to the MCP server. Use for authentication + or other purposes. - - `"in_progress"` + - `require_approval: optional object { always, never } or "always" or "never"` - - `"completed"` + Specify which of the MCP server's tools require approval. - - `"incomplete"` + - `McpToolApprovalFilter object { always, never }` - - `tools: array of object { name, parameters, strict, 3 more } or object { type, vector_store_ids, filters, 2 more } or object { type } or 12 more` + Specify which of the MCP server's tools require approval. Can be + `always`, `never`, or a filter object associated with tools + that require approval. - The loaded tool definitions returned by tool search. + - `always: optional object { read_only, tool_names }` - - `Function object { name, parameters, strict, 3 more }` + A filter object to specify which tools are allowed. - 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). + - `read_only: optional boolean` - - `name: string` + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. - The name of the function to call. + - `tool_names: optional array of string` - - `parameters: map[unknown]` + List of allowed tool names. - A JSON schema object describing the parameters of the function. + - `never: optional object { read_only, tool_names }` - - `strict: boolean` + A filter object to specify which tools are allowed. - Whether to enforce strict parameter validation. Default `true`. + - `read_only: optional boolean` - - `type: "function"` + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. - The type of the function tool. Always `function`. + - `tool_names: optional array of string` - - `"function"` + List of allowed tool names. - - `defer_loading: optional boolean` + - `McpToolApprovalSetting = "always" or "never"` - Whether this function is deferred and loaded via tool search. + Specify a single approval policy for all tools. One of `always` or + `never`. When set to `always`, all tools will require approval. When + set to `never`, all tools will not require approval. - - `description: optional string` + - `"always"` - A description of the function. Used by the model to determine whether or not to call the function. + - `"never"` - - `FileSearch object { type, vector_store_ids, filters, 2 more }` + - `server_description: optional string` - 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). + Optional description of the MCP server, used to provide more context. - - `type: "file_search"` + - `server_url: optional string` - The type of the file search tool. Always `file_search`. + The URL for the MCP server. One of `server_url` or `connector_id` must be + provided. - - `"file_search"` + - `CodeInterpreter object { container, type }` - - `vector_store_ids: array of string` + A tool that runs Python code to help generate a response to a prompt. - The IDs of the vector stores to search. + - `container: string or object { type, file_ids, memory_limit, network_policy }` - - `filters: optional ComparisonFilter or CompoundFilter` + The code interpreter container. Can be a container ID or an object that + specifies uploaded file IDs to make available to your code, along with an + optional `memory_limit` setting. - A filter to apply. + - `string` - - `ComparisonFilter object { key, type, value }` + The container ID. - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + - `CodeInterpreterToolAuto object { type, file_ids, memory_limit, network_policy }` - - `key: string` + Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. - The key to compare against the value. + - `type: "auto"` - - `type: "eq" or "ne" or "gt" or 5 more` + Always `auto`. - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + - `"auto"` - - `eq`: equals - - `ne`: not equal - - `gt`: greater than - - `gte`: greater than or equal - - `lt`: less than - - `lte`: less than or equal - - `in`: in - - `nin`: not in + - `file_ids: optional array of string` - - `"eq"` + An optional list of uploaded files to make available to your code. - - `"ne"` + - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` - - `"gt"` + The memory limit for the code interpreter container. - - `"gte"` + - `"1g"` - - `"lt"` + - `"4g"` - - `"lte"` + - `"16g"` - - `"in"` + - `"64g"` - - `"nin"` + - `network_policy: optional ContainerNetworkPolicyDisabled or ContainerNetworkPolicyAllowlist` - - `value: string or number or boolean or array of string or number` + Network access policy for the container. - The value to compare against the attribute key; supports string, number, or boolean types. + - `ContainerNetworkPolicyDisabled object { type }` - - `string` + - `type: "disabled"` - - `number` + Disable outbound network access. Always `disabled`. - - `boolean` + - `"disabled"` - - `array of string or number` + - `ContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` - - `string` + - `allowed_domains: array of string` - - `number` + A list of allowed domains when type is `allowlist`. - - `CompoundFilter object { filters, type }` + - `type: "allowlist"` - Combine multiple filters using `and` or `or`. + Allow outbound network access only to specified domains. Always `allowlist`. - - `filters: array of ComparisonFilter or unknown` + - `"allowlist"` - Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. + - `domain_secrets: optional array of ContainerNetworkPolicyDomainSecret` - - `ComparisonFilter object { key, type, value }` + Optional domain-scoped secrets for allowlisted domains. - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + - `domain: string` - - `unknown` + The domain associated with the secret. - - `type: "and" or "or"` + - `name: string` - Type of operation: `and` or `or`. + The name of the secret to inject for the domain. - - `"and"` + - `value: string` - - `"or"` + The secret value to inject for the domain. - - `max_num_results: optional number` + - `type: "code_interpreter"` - The maximum number of results to return. This number should be between 1 and 50 inclusive. + The type of the code interpreter tool. Always `code_interpreter`. - - `ranking_options: optional object { hybrid_search, ranker, score_threshold }` + - `"code_interpreter"` - Ranking options for search. + - `ImageGeneration object { type, action, background, 9 more }` - - `hybrid_search: optional object { embedding_weight, text_weight }` + A tool that generates images using the GPT image models. - Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. + - `type: "image_generation"` - - `embedding_weight: number` + The type of the image generation tool. Always `image_generation`. - The weight of the embedding in the reciprocal ranking fusion. + - `"image_generation"` - - `text_weight: number` + - `action: optional "generate" or "edit" or "auto"` - The weight of the text in the reciprocal ranking fusion. + Whether to generate a new image or edit an existing image. Default: `auto`. - - `ranker: optional "auto" or "default-2024-11-15"` + - `"generate"` - The ranker to use for the file search. + - `"edit"` - `"auto"` - - `"default-2024-11-15"` + - `background: optional "transparent" or "opaque" or "auto"` - - `score_threshold: optional number` + Background type for the generated image. One of `transparent`, + `opaque`, or `auto`. Default: `auto`. - The score threshold for the file search, a number between 0 and 1. Numbers closer to 1 will attempt to return only the most relevant results, but may return fewer results. + - `"transparent"` - - `Computer object { type }` + - `"opaque"` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `"auto"` - - `type: "computer"` + - `input_fidelity: optional "high" or "low"` - The type of the computer tool. Always `computer`. + Control how much effort the model will exert to match the style and features, especially facial features, of input images. This parameter is only supported for `gpt-image-1` and `gpt-image-1.5` and later models, unsupported for `gpt-image-1-mini`. Supports `high` and `low`. Defaults to `low`. - - `"computer"` + - `"high"` - - `ComputerUsePreview object { display_height, display_width, environment, type }` + - `"low"` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `input_image_mask: optional object { file_id, image_url }` - - `display_height: number` + Optional mask for inpainting. Contains `image_url` + (string, optional) and `file_id` (string, optional). - The height of the computer display. + - `file_id: optional string` - - `display_width: number` + File ID for the mask image. - The width of the computer display. + - `image_url: optional string` - - `environment: "windows" or "mac" or "linux" or 2 more` + Base64-encoded mask image. - The type of computer environment to control. + - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` - - `"windows"` + The image generation model to use. Default: `gpt-image-1`. - - `"mac"` + - `string` - - `"linux"` + - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` - - `"ubuntu"` + The image generation model to use. Default: `gpt-image-1`. - - `"browser"` + - `"gpt-image-1"` - - `type: "computer_use_preview"` + - `"gpt-image-1-mini"` - The type of the computer use tool. Always `computer_use_preview`. + - `"gpt-image-1.5"` - - `"computer_use_preview"` + - `moderation: optional "auto" or "low"` - - `WebSearch object { type, filters, search_context_size, user_location }` + Moderation level for the generated image. Default: `auto`. - Search the Internet for sources related to the prompt. Learn more about the - [web search tool](/docs/guides/tools-web-search). + - `"auto"` - - `type: "web_search" or "web_search_2025_08_26"` + - `"low"` - The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. + - `output_compression: optional number` - - `"web_search"` + Compression level for the output image. Default: 100. - - `"web_search_2025_08_26"` + - `output_format: optional "png" or "webp" or "jpeg"` - - `filters: optional object { allowed_domains }` + The output format of the generated image. One of `png`, `webp`, or + `jpeg`. Default: `png`. - Filters for the search. + - `"png"` - - `allowed_domains: optional array of string` + - `"webp"` - Allowed domains for the search. If not provided, all domains are allowed. - Subdomains of the provided domains are allowed as well. + - `"jpeg"` - Example: `["pubmed.ncbi.nlm.nih.gov"]` + - `partial_images: optional number` - - `search_context_size: optional "low" or "medium" or "high"` + Number of partial images to generate in streaming mode, from 0 (default value) to 3. - High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. + - `quality: optional "low" or "medium" or "high" or "auto"` + + The quality of the generated image. One of `low`, `medium`, `high`, + or `auto`. Default: `auto`. - `"low"` @@ -7739,4927 +13304,4853 @@ Create items in a conversation with the given ID. - `"high"` - - `user_location: optional object { city, country, region, 2 more }` - - The approximate location of the user. - - - `city: optional string` - - Free text input for the city of the user, e.g. `San Francisco`. + - `"auto"` - - `country: optional string` + - `size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or "auto"` - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. - - `region: optional string` + - `string` - Free text input for the region of the user, e.g. `California`. + - `"1024x1024" or "1024x1536" or "1536x1024" or "auto"` - - `timezone: optional string` + The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + - `"1024x1024"` - - `type: optional "approximate"` + - `"1024x1536"` - The type of location approximation. Always `approximate`. + - `"1536x1024"` - - `"approximate"` + - `"auto"` - - `Mcp object { server_label, type, allowed_tools, 7 more }` + - `LocalShell object { type }` - Give the model access to additional tools via remote Model Context Protocol - (MCP) servers. [Learn more about MCP](/docs/guides/tools-remote-mcp). + A tool that allows the model to execute shell commands in a local environment. - - `server_label: string` + - `type: "local_shell"` - A label for this MCP server, used to identify it in tool calls. + The type of the local shell tool. Always `local_shell`. - - `type: "mcp"` + - `"local_shell"` - The type of the MCP tool. Always `mcp`. + - `Shell object { type, environment }` - - `"mcp"` + A tool that allows the model to execute shell commands. - - `allowed_tools: optional array of string or object { read_only, tool_names }` + - `type: "shell"` - List of allowed tool names or a filter object. + The type of the shell tool. Always `shell`. - - `McpAllowedTools = array of string` + - `"shell"` - A string array of allowed tool names + - `environment: optional ContainerAuto or LocalEnvironment or ContainerReference` - - `McpToolFilter object { read_only, tool_names }` + - `ContainerAuto object { type, file_ids, memory_limit, 2 more }` - A filter object to specify which tools are allowed. + - `type: "container_auto"` - - `read_only: optional boolean` + Automatically creates a container for this request - Indicates whether or not a tool modifies data or is read-only. If an - MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), - it will match this filter. + - `"container_auto"` - - `tool_names: optional array of string` + - `file_ids: optional array of string` - List of allowed tool names. + An optional list of uploaded files to make available to your code. - - `authorization: optional string` + - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` - An OAuth access token that can be used with a remote MCP server, either - with a custom MCP server URL or a service connector. Your application - must handle the OAuth authorization flow and provide the token here. + The memory limit for the container. - - `connector_id: optional "connector_dropbox" or "connector_gmail" or "connector_googlecalendar" or 5 more` + - `"1g"` - Identifier for service connectors, like those available in ChatGPT. One of - `server_url` or `connector_id` must be provided. Learn more about service - connectors [here](/docs/guides/tools-remote-mcp#connectors). + - `"4g"` - Currently supported `connector_id` values are: + - `"16g"` - - Dropbox: `connector_dropbox` - - Gmail: `connector_gmail` - - Google Calendar: `connector_googlecalendar` - - Google Drive: `connector_googledrive` - - Microsoft Teams: `connector_microsoftteams` - - Outlook Calendar: `connector_outlookcalendar` - - Outlook Email: `connector_outlookemail` - - SharePoint: `connector_sharepoint` + - `"64g"` - - `"connector_dropbox"` + - `network_policy: optional ContainerNetworkPolicyDisabled or ContainerNetworkPolicyAllowlist` - - `"connector_gmail"` + Network access policy for the container. - - `"connector_googlecalendar"` + - `ContainerNetworkPolicyDisabled object { type }` - - `"connector_googledrive"` + - `ContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` - - `"connector_microsoftteams"` + - `skills: optional array of SkillReference or InlineSkill` - - `"connector_outlookcalendar"` + An optional list of skills referenced by id or inline data. - - `"connector_outlookemail"` + - `SkillReference object { skill_id, type, version }` - - `"connector_sharepoint"` + - `skill_id: string` - - `defer_loading: optional boolean` + The ID of the referenced skill. - Whether this MCP tool is deferred and discovered via tool search. + - `type: "skill_reference"` - - `headers: optional map[string]` + References a skill created with the /v1/skills endpoint. - Optional HTTP headers to send to the MCP server. Use for authentication - or other purposes. + - `"skill_reference"` - - `require_approval: optional object { always, never } or "always" or "never"` + - `version: optional string` - Specify which of the MCP server's tools require approval. + Optional skill version. Use a positive integer or 'latest'. Omit for default. - - `McpToolApprovalFilter object { always, never }` + - `InlineSkill object { description, name, source, type }` - Specify which of the MCP server's tools require approval. Can be - `always`, `never`, or a filter object associated with tools - that require approval. + - `description: string` - - `always: optional object { read_only, tool_names }` + The description of the skill. - A filter object to specify which tools are allowed. + - `name: string` - - `read_only: optional boolean` + The name of the skill. - Indicates whether or not a tool modifies data or is read-only. If an - MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), - it will match this filter. + - `source: InlineSkillSource` - - `tool_names: optional array of string` + Inline skill payload - List of allowed tool names. + - `data: string` - - `never: optional object { read_only, tool_names }` + Base64-encoded skill zip bundle. - A filter object to specify which tools are allowed. + - `media_type: "application/zip"` - - `read_only: optional boolean` + The media type of the inline skill payload. Must be `application/zip`. - Indicates whether or not a tool modifies data or is read-only. If an - MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), - it will match this filter. + - `"application/zip"` - - `tool_names: optional array of string` + - `type: "base64"` - List of allowed tool names. + The type of the inline skill source. Must be `base64`. - - `McpToolApprovalSetting = "always" or "never"` + - `"base64"` - Specify a single approval policy for all tools. One of `always` or - `never`. When set to `always`, all tools will require approval. When - set to `never`, all tools will not require approval. + - `type: "inline"` - - `"always"` + Defines an inline skill for this request. - - `"never"` + - `"inline"` - - `server_description: optional string` + - `LocalEnvironment object { type, skills }` - Optional description of the MCP server, used to provide more context. + - `type: "local"` - - `server_url: optional string` + Use a local computer environment. - The URL for the MCP server. One of `server_url` or `connector_id` must be - provided. + - `"local"` - - `CodeInterpreter object { container, type }` + - `skills: optional array of LocalSkill` - A tool that runs Python code to help generate a response to a prompt. + An optional list of skills. - - `container: string or object { type, file_ids, memory_limit, network_policy }` + - `description: string` - The code interpreter container. Can be a container ID or an object that - specifies uploaded file IDs to make available to your code, along with an - optional `memory_limit` setting. + The description of the skill. - - `string` + - `name: string` - The container ID. + The name of the skill. - - `CodeInterpreterToolAuto object { type, file_ids, memory_limit, network_policy }` + - `path: string` - Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. + The path to the directory containing the skill. - - `type: "auto"` + - `ContainerReference object { container_id, type }` - Always `auto`. + - `container_id: string` - - `"auto"` + The ID of the referenced container. - - `file_ids: optional array of string` + - `type: "container_reference"` - An optional list of uploaded files to make available to your code. + References a container created with the /v1/containers endpoint - - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` + - `"container_reference"` - The memory limit for the code interpreter container. + - `Custom object { name, type, defer_loading, 2 more }` - - `"1g"` + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) - - `"4g"` + - `name: string` - - `"16g"` + The name of the custom tool, used to identify it in tool calls. - - `"64g"` + - `type: "custom"` - - `network_policy: optional ContainerNetworkPolicyDisabled or ContainerNetworkPolicyAllowlist` + The type of the custom tool. Always `custom`. - Network access policy for the container. + - `"custom"` - - `ContainerNetworkPolicyDisabled object { type }` + - `defer_loading: optional boolean` - - `type: "disabled"` + Whether this tool should be deferred and discovered via tool search. - Disable outbound network access. Always `disabled`. + - `description: optional string` - - `"disabled"` + Optional description of the custom tool, used to provide more context. - - `ContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` + - `format: optional CustomToolInputFormat` - - `allowed_domains: array of string` + The input format for the custom tool. Default is unconstrained text. - A list of allowed domains when type is `allowlist`. + - `Text object { type }` - - `type: "allowlist"` + Unconstrained free-form text. - Allow outbound network access only to specified domains. Always `allowlist`. + - `type: "text"` - - `"allowlist"` + Unconstrained text format. Always `text`. - - `domain_secrets: optional array of ContainerNetworkPolicyDomainSecret` + - `"text"` - Optional domain-scoped secrets for allowlisted domains. + - `Grammar object { definition, syntax, type }` - - `domain: string` + A grammar defined by the user. - The domain associated with the secret. + - `definition: string` - - `name: string` + The grammar definition. - The name of the secret to inject for the domain. + - `syntax: "lark" or "regex"` - - `value: string` + The syntax of the grammar definition. One of `lark` or `regex`. - The secret value to inject for the domain. + - `"lark"` - - `type: "code_interpreter"` + - `"regex"` - The type of the code interpreter tool. Always `code_interpreter`. + - `type: "grammar"` - - `"code_interpreter"` + Grammar format. Always `grammar`. - - `ImageGeneration object { type, action, background, 9 more }` + - `"grammar"` - A tool that generates images using the GPT image models. + - `Namespace object { description, name, tools, type }` - - `type: "image_generation"` + Groups function/custom tools under a shared namespace. - The type of the image generation tool. Always `image_generation`. + - `description: string` - - `"image_generation"` + A description of the namespace shown to the model. - - `action: optional "generate" or "edit" or "auto"` + - `name: string` - Whether to generate a new image or edit an existing image. Default: `auto`. + The namespace name used in tool calls (for example, `crm`). - - `"generate"` + - `tools: array of object { name, type, defer_loading, 3 more } or object { name, type, defer_loading, 2 more }` - - `"edit"` + The function/custom tools available inside this namespace. - - `"auto"` + - `Function object { name, type, defer_loading, 3 more }` - - `background: optional "transparent" or "opaque" or "auto"` + - `name: string` - Background type for the generated image. One of `transparent`, - `opaque`, or `auto`. Default: `auto`. + - `type: "function"` - - `"transparent"` + - `"function"` - - `"opaque"` + - `defer_loading: optional boolean` - - `"auto"` + Whether this function should be deferred and discovered via tool search. - - `input_fidelity: optional "high" or "low"` + - `description: optional string` - Control how much effort the model will exert to match the style and features, especially facial features, of input images. This parameter is only supported for `gpt-image-1` and `gpt-image-1.5` and later models, unsupported for `gpt-image-1-mini`. Supports `high` and `low`. Defaults to `low`. + - `parameters: optional unknown` - - `"high"` + - `strict: optional boolean` - - `"low"` + - `Custom object { name, type, defer_loading, 2 more }` - - `input_image_mask: optional object { file_id, image_url }` + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) - Optional mask for inpainting. Contains `image_url` - (string, optional) and `file_id` (string, optional). + - `name: string` - - `file_id: optional string` + The name of the custom tool, used to identify it in tool calls. - File ID for the mask image. + - `type: "custom"` - - `image_url: optional string` + The type of the custom tool. Always `custom`. - Base64-encoded mask image. + - `"custom"` - - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` + - `defer_loading: optional boolean` - The image generation model to use. Default: `gpt-image-1`. + Whether this tool should be deferred and discovered via tool search. - - `string` + - `description: optional string` - - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` + Optional description of the custom tool, used to provide more context. - The image generation model to use. Default: `gpt-image-1`. + - `format: optional CustomToolInputFormat` - - `"gpt-image-1"` + The input format for the custom tool. Default is unconstrained text. - - `"gpt-image-1-mini"` + - `type: "namespace"` - - `"gpt-image-1.5"` + The type of the tool. Always `namespace`. - - `moderation: optional "auto" or "low"` + - `"namespace"` - Moderation level for the generated image. Default: `auto`. + - `ToolSearch object { type, description, execution, parameters }` - - `"auto"` + Hosted or BYOT tool search configuration for deferred tools. - - `"low"` + - `type: "tool_search"` - - `output_compression: optional number` + The type of the tool. Always `tool_search`. - Compression level for the output image. Default: 100. + - `"tool_search"` - - `output_format: optional "png" or "webp" or "jpeg"` + - `description: optional string` - The output format of the generated image. One of `png`, `webp`, or - `jpeg`. Default: `png`. + Description shown to the model for a client-executed tool search tool. - - `"png"` + - `execution: optional "server" or "client"` - - `"webp"` + Whether tool search is executed by the server or by the client. - - `"jpeg"` + - `"server"` - - `partial_images: optional number` + - `"client"` - Number of partial images to generate in streaming mode, from 0 (default value) to 3. + - `parameters: optional unknown` - - `quality: optional "low" or "medium" or "high" or "auto"` + Parameter schema for a client-executed tool search tool. - The quality of the generated image. One of `low`, `medium`, `high`, - or `auto`. Default: `auto`. + - `WebSearchPreview object { type, search_content_types, search_context_size, user_location }` - - `"low"` + This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - - `"medium"` + - `type: "web_search_preview" or "web_search_preview_2025_03_11"` - - `"high"` + The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. - - `"auto"` + - `"web_search_preview"` - - `size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or "auto"` + - `"web_search_preview_2025_03_11"` - The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. + - `search_content_types: optional array of "text" or "image"` - - `string` + - `"text"` - - `"1024x1024" or "1024x1536" or "1536x1024" or "auto"` + - `"image"` - The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. + - `search_context_size: optional "low" or "medium" or "high"` - - `"1024x1024"` + High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. - - `"1024x1536"` + - `"low"` - - `"1536x1024"` + - `"medium"` - - `"auto"` + - `"high"` - - `LocalShell object { type }` + - `user_location: optional object { type, city, country, 2 more }` - A tool that allows the model to execute shell commands in a local environment. + The user's location. - - `type: "local_shell"` + - `type: "approximate"` - The type of the local shell tool. Always `local_shell`. + The type of location approximation. Always `approximate`. - - `"local_shell"` + - `"approximate"` - - `Shell object { type, environment }` + - `city: optional string` - A tool that allows the model to execute shell commands. + Free text input for the city of the user, e.g. `San Francisco`. - - `type: "shell"` + - `country: optional string` - The type of the shell tool. Always `shell`. + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - - `"shell"` + - `region: optional string` - - `environment: optional ContainerAuto or LocalEnvironment or ContainerReference` + Free text input for the region of the user, e.g. `California`. - - `ContainerAuto object { type, file_ids, memory_limit, 2 more }` + - `timezone: optional string` - - `type: "container_auto"` + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - Automatically creates a container for this request + - `ApplyPatch object { type }` - - `"container_auto"` + Allows the assistant to create, delete, or update files using unified diffs. - - `file_ids: optional array of string` + - `type: "apply_patch"` - An optional list of uploaded files to make available to your code. + The type of the tool. Always `apply_patch`. - - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` + - `"apply_patch"` - The memory limit for the container. + - `type: "tool_search_output"` - - `"1g"` + The type of the item. Always `tool_search_output`. - - `"4g"` + - `"tool_search_output"` - - `"16g"` + - `created_by: optional string` - - `"64g"` + The identifier of the actor that created the item. - - `network_policy: optional ContainerNetworkPolicyDisabled or ContainerNetworkPolicyAllowlist` + - `AdditionalTools object { id, role, tools, type }` - Network access policy for the container. + - `id: string` - - `ContainerNetworkPolicyDisabled object { type }` + The unique ID of the additional tools item. - - `ContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` + - `role: "unknown" or "user" or "assistant" or 5 more` - - `skills: optional array of SkillReference or InlineSkill` + The role that provided the additional tools. - An optional list of skills referenced by id or inline data. + - `"unknown"` - - `SkillReference object { skill_id, type, version }` + - `"user"` - - `skill_id: string` + - `"assistant"` - The ID of the referenced skill. + - `"system"` - - `type: "skill_reference"` + - `"critic"` - References a skill created with the /v1/skills endpoint. + - `"discriminator"` - - `"skill_reference"` + - `"developer"` - - `version: optional string` + - `"tool"` - Optional skill version. Use a positive integer or 'latest'. Omit for default. + - `tools: array of object { name, parameters, strict, 3 more } or object { type, vector_store_ids, filters, 2 more } or object { type } or 12 more` - - `InlineSkill object { description, name, source, type }` + The additional tool definitions made available at this item. - - `description: string` + - `Function object { name, parameters, strict, 3 more }` - The description of the skill. + Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). - `name: string` - The name of the skill. - - - `source: InlineSkillSource` + The name of the function to call. - Inline skill payload + - `parameters: map[unknown]` - - `data: string` + A JSON schema object describing the parameters of the function. - Base64-encoded skill zip bundle. + - `strict: boolean` - - `media_type: "application/zip"` + Whether to enforce strict parameter validation. Default `true`. - The media type of the inline skill payload. Must be `application/zip`. + - `type: "function"` - - `"application/zip"` + The type of the function tool. Always `function`. - - `type: "base64"` + - `"function"` - The type of the inline skill source. Must be `base64`. + - `defer_loading: optional boolean` - - `"base64"` + Whether this function is deferred and loaded via tool search. - - `type: "inline"` + - `description: optional string` - Defines an inline skill for this request. + A description of the function. Used by the model to determine whether or not to call the function. - - `"inline"` + - `FileSearch object { type, vector_store_ids, filters, 2 more }` - - `LocalEnvironment object { type, skills }` + A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). - - `type: "local"` + - `type: "file_search"` - Use a local computer environment. + The type of the file search tool. Always `file_search`. - - `"local"` + - `"file_search"` - - `skills: optional array of LocalSkill` + - `vector_store_ids: array of string` - An optional list of skills. + The IDs of the vector stores to search. - - `description: string` + - `filters: optional ComparisonFilter or CompoundFilter` - The description of the skill. + A filter to apply. - - `name: string` + - `ComparisonFilter object { key, type, value }` - The name of the skill. + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - - `path: string` + - `CompoundFilter object { filters, type }` - The path to the directory containing the skill. + Combine multiple filters using `and` or `or`. - - `ContainerReference object { container_id, type }` + - `max_num_results: optional number` - - `container_id: string` + The maximum number of results to return. This number should be between 1 and 50 inclusive. - The ID of the referenced container. + - `ranking_options: optional object { hybrid_search, ranker, score_threshold }` - - `type: "container_reference"` + Ranking options for search. - References a container created with the /v1/containers endpoint + - `hybrid_search: optional object { embedding_weight, text_weight }` - - `"container_reference"` + Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. - - `Custom object { name, type, defer_loading, 2 more }` + - `embedding_weight: number` - A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) + The weight of the embedding in the reciprocal ranking fusion. - - `name: string` + - `text_weight: number` - The name of the custom tool, used to identify it in tool calls. + The weight of the text in the reciprocal ranking fusion. - - `type: "custom"` + - `ranker: optional "auto" or "default-2024-11-15"` - The type of the custom tool. Always `custom`. + The ranker to use for the file search. - - `"custom"` + - `"auto"` - - `defer_loading: optional boolean` + - `"default-2024-11-15"` - Whether this tool should be deferred and discovered via tool search. + - `score_threshold: optional number` - - `description: optional string` + The score threshold for the file search, a number between 0 and 1. Numbers closer to 1 will attempt to return only the most relevant results, but may return fewer results. - Optional description of the custom tool, used to provide more context. + - `Computer object { type }` - - `format: optional CustomToolInputFormat` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - The input format for the custom tool. Default is unconstrained text. + - `type: "computer"` - - `Text object { type }` + The type of the computer tool. Always `computer`. - Unconstrained free-form text. + - `"computer"` - - `type: "text"` + - `ComputerUsePreview object { display_height, display_width, environment, type }` - Unconstrained text format. Always `text`. + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `"text"` + - `display_height: number` - - `Grammar object { definition, syntax, type }` + The height of the computer display. - A grammar defined by the user. + - `display_width: number` - - `definition: string` + The width of the computer display. - The grammar definition. + - `environment: "windows" or "mac" or "linux" or 2 more` - - `syntax: "lark" or "regex"` + The type of computer environment to control. - The syntax of the grammar definition. One of `lark` or `regex`. + - `"windows"` - - `"lark"` + - `"mac"` - - `"regex"` + - `"linux"` - - `type: "grammar"` + - `"ubuntu"` - Grammar format. Always `grammar`. + - `"browser"` - - `"grammar"` + - `type: "computer_use_preview"` - - `Namespace object { description, name, tools, type }` + The type of the computer use tool. Always `computer_use_preview`. - Groups function/custom tools under a shared namespace. + - `"computer_use_preview"` - - `description: string` + - `WebSearch object { type, filters, search_context_size, user_location }` - A description of the namespace shown to the model. + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](/docs/guides/tools-web-search). - - `name: string` + - `type: "web_search" or "web_search_2025_08_26"` - The namespace name used in tool calls (for example, `crm`). + The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. - - `tools: array of object { name, type, defer_loading, 3 more } or object { name, type, defer_loading, 2 more }` + - `"web_search"` - The function/custom tools available inside this namespace. + - `"web_search_2025_08_26"` - - `Function object { name, type, defer_loading, 3 more }` + - `filters: optional object { allowed_domains }` - - `name: string` + Filters for the search. - - `type: "function"` + - `allowed_domains: optional array of string` - - `"function"` + Allowed domains for the search. If not provided, all domains are allowed. + Subdomains of the provided domains are allowed as well. - - `defer_loading: optional boolean` + Example: `["pubmed.ncbi.nlm.nih.gov"]` - Whether this function should be deferred and discovered via tool search. + - `search_context_size: optional "low" or "medium" or "high"` - - `description: optional string` + High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. - - `parameters: optional unknown` + - `"low"` - - `strict: optional boolean` + - `"medium"` - - `Custom object { name, type, defer_loading, 2 more }` + - `"high"` - A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) + - `user_location: optional object { city, country, region, 2 more }` - - `name: string` + The approximate location of the user. - The name of the custom tool, used to identify it in tool calls. + - `city: optional string` - - `type: "custom"` + Free text input for the city of the user, e.g. `San Francisco`. - The type of the custom tool. Always `custom`. + - `country: optional string` - - `"custom"` + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - - `defer_loading: optional boolean` + - `region: optional string` - Whether this tool should be deferred and discovered via tool search. + Free text input for the region of the user, e.g. `California`. - - `description: optional string` + - `timezone: optional string` - Optional description of the custom tool, used to provide more context. + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - - `format: optional CustomToolInputFormat` + - `type: optional "approximate"` - The input format for the custom tool. Default is unconstrained text. + The type of location approximation. Always `approximate`. - - `type: "namespace"` + - `"approximate"` - The type of the tool. Always `namespace`. + - `Mcp object { server_label, type, allowed_tools, 7 more }` - - `"namespace"` + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](/docs/guides/tools-remote-mcp). - - `ToolSearch object { type, description, execution, parameters }` + - `server_label: string` - Hosted or BYOT tool search configuration for deferred tools. + A label for this MCP server, used to identify it in tool calls. - - `type: "tool_search"` + - `type: "mcp"` - The type of the tool. Always `tool_search`. + The type of the MCP tool. Always `mcp`. - - `"tool_search"` + - `"mcp"` - - `description: optional string` + - `allowed_tools: optional array of string or object { read_only, tool_names }` - Description shown to the model for a client-executed tool search tool. + List of allowed tool names or a filter object. - - `execution: optional "server" or "client"` + - `McpAllowedTools = array of string` - Whether tool search is executed by the server or by the client. + A string array of allowed tool names - - `"server"` + - `McpToolFilter object { read_only, tool_names }` - - `"client"` + A filter object to specify which tools are allowed. - - `parameters: optional unknown` + - `read_only: optional boolean` - Parameter schema for a client-executed tool search tool. + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. - - `WebSearchPreview object { type, search_content_types, search_context_size, user_location }` + - `tool_names: optional array of string` - This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + List of allowed tool names. - - `type: "web_search_preview" or "web_search_preview_2025_03_11"` + - `authorization: optional string` - The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. + An OAuth access token that can be used with a remote MCP server, either + with a custom MCP server URL or a service connector. Your application + must handle the OAuth authorization flow and provide the token here. - - `"web_search_preview"` + - `connector_id: optional "connector_dropbox" or "connector_gmail" or "connector_googlecalendar" or 5 more` - - `"web_search_preview_2025_03_11"` + Identifier for service connectors, like those available in ChatGPT. One of + `server_url` or `connector_id` must be provided. Learn more about service + connectors [here](/docs/guides/tools-remote-mcp#connectors). - - `search_content_types: optional array of "text" or "image"` + Currently supported `connector_id` values are: - - `"text"` + - Dropbox: `connector_dropbox` + - Gmail: `connector_gmail` + - Google Calendar: `connector_googlecalendar` + - Google Drive: `connector_googledrive` + - Microsoft Teams: `connector_microsoftteams` + - Outlook Calendar: `connector_outlookcalendar` + - Outlook Email: `connector_outlookemail` + - SharePoint: `connector_sharepoint` - - `"image"` + - `"connector_dropbox"` - - `search_context_size: optional "low" or "medium" or "high"` + - `"connector_gmail"` - High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. + - `"connector_googlecalendar"` - - `"low"` + - `"connector_googledrive"` - - `"medium"` + - `"connector_microsoftteams"` - - `"high"` + - `"connector_outlookcalendar"` - - `user_location: optional object { type, city, country, 2 more }` + - `"connector_outlookemail"` - The user's location. + - `"connector_sharepoint"` - - `type: "approximate"` + - `defer_loading: optional boolean` - The type of location approximation. Always `approximate`. + Whether this MCP tool is deferred and discovered via tool search. - - `"approximate"` + - `headers: optional map[string]` - - `city: optional string` + Optional HTTP headers to send to the MCP server. Use for authentication + or other purposes. - Free text input for the city of the user, e.g. `San Francisco`. + - `require_approval: optional object { always, never } or "always" or "never"` - - `country: optional string` + Specify which of the MCP server's tools require approval. - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + - `McpToolApprovalFilter object { always, never }` - - `region: optional string` + Specify which of the MCP server's tools require approval. Can be + `always`, `never`, or a filter object associated with tools + that require approval. - Free text input for the region of the user, e.g. `California`. + - `always: optional object { read_only, tool_names }` - - `timezone: optional string` + A filter object to specify which tools are allowed. - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + - `read_only: optional boolean` - - `ApplyPatch object { type }` + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. - Allows the assistant to create, delete, or update files using unified diffs. + - `tool_names: optional array of string` - - `type: "apply_patch"` + List of allowed tool names. - The type of the tool. Always `apply_patch`. + - `never: optional object { read_only, tool_names }` - - `"apply_patch"` + A filter object to specify which tools are allowed. - - `type: "tool_search_output"` + - `read_only: optional boolean` - The type of the item. Always `tool_search_output`. + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. - - `"tool_search_output"` + - `tool_names: optional array of string` - - `created_by: optional string` + List of allowed tool names. - The identifier of the actor that created the item. + - `McpToolApprovalSetting = "always" or "never"` - - `Reasoning object { id, summary, type, 3 more }` + Specify a single approval policy for all tools. One of `always` or + `never`. When set to `always`, all tools will require approval. When + set to `never`, all tools will not require approval. - 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). + - `"always"` - - `id: string` + - `"never"` - The unique identifier of the reasoning content. + - `server_description: optional string` - - `summary: array of SummaryTextContent` + Optional description of the MCP server, used to provide more context. - Reasoning summary content. + - `server_url: optional string` - - `text: string` + The URL for the MCP server. One of `server_url` or `connector_id` must be + provided. - A summary of the reasoning output from the model so far. + - `CodeInterpreter object { container, type }` - - `type: "summary_text"` + A tool that runs Python code to help generate a response to a prompt. - The type of the object. Always `summary_text`. + - `container: string or object { type, file_ids, memory_limit, network_policy }` - - `type: "reasoning"` + The code interpreter container. Can be a container ID or an object that + specifies uploaded file IDs to make available to your code, along with an + optional `memory_limit` setting. - The type of the object. Always `reasoning`. + - `string` - - `"reasoning"` + The container ID. - - `content: optional array of object { text, type }` + - `CodeInterpreterToolAuto object { type, file_ids, memory_limit, network_policy }` - Reasoning text content. + Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. - - `text: string` + - `type: "auto"` - The reasoning text from the model. + Always `auto`. - - `type: "reasoning_text"` + - `"auto"` - The type of the reasoning text. Always `reasoning_text`. + - `file_ids: optional array of string` - - `"reasoning_text"` + An optional list of uploaded files to make available to your code. - - `encrypted_content: optional string` + - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` - The encrypted content of the reasoning item - populated when a response is - generated with `reasoning.encrypted_content` in the `include` parameter. + The memory limit for the code interpreter container. - - `status: optional "in_progress" or "completed" or "incomplete"` + - `"1g"` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `"4g"` - - `"in_progress"` + - `"16g"` - - `"completed"` + - `"64g"` - - `"incomplete"` + - `network_policy: optional ContainerNetworkPolicyDisabled or ContainerNetworkPolicyAllowlist` - - `Compaction object { id, encrypted_content, type, created_by }` + Network access policy for the container. - A compaction item generated by the [`v1/responses/compact` API](/docs/api-reference/responses/compact). + - `ContainerNetworkPolicyDisabled object { type }` - - `id: string` + - `ContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` - The unique ID of the compaction item. + - `type: "code_interpreter"` - - `encrypted_content: string` + The type of the code interpreter tool. Always `code_interpreter`. - The encrypted content that was produced by compaction. + - `"code_interpreter"` - - `type: "compaction"` + - `ImageGeneration object { type, action, background, 9 more }` - The type of the item. Always `compaction`. + A tool that generates images using the GPT image models. - - `"compaction"` + - `type: "image_generation"` - - `created_by: optional string` + The type of the image generation tool. Always `image_generation`. - The identifier of the actor that created the item. + - `"image_generation"` - - `CodeInterpreterCall object { id, code, container_id, 3 more }` + - `action: optional "generate" or "edit" or "auto"` - A tool call to run code. + Whether to generate a new image or edit an existing image. Default: `auto`. - - `id: string` + - `"generate"` - The unique ID of the code interpreter tool call. + - `"edit"` - - `code: string` + - `"auto"` - The code to run, or null if not available. + - `background: optional "transparent" or "opaque" or "auto"` - - `container_id: string` + Background type for the generated image. One of `transparent`, + `opaque`, or `auto`. Default: `auto`. - The ID of the container used to run the code. + - `"transparent"` - - `outputs: array of object { logs, type } or object { type, url }` + - `"opaque"` - The outputs generated by the code interpreter, such as logs or images. - Can be null if no outputs are available. + - `"auto"` - - `Logs object { logs, type }` + - `input_fidelity: optional "high" or "low"` - The logs output from the code interpreter. + Control how much effort the model will exert to match the style and features, especially facial features, of input images. This parameter is only supported for `gpt-image-1` and `gpt-image-1.5` and later models, unsupported for `gpt-image-1-mini`. Supports `high` and `low`. Defaults to `low`. - - `logs: string` + - `"high"` - The logs output from the code interpreter. + - `"low"` - - `type: "logs"` + - `input_image_mask: optional object { file_id, image_url }` - The type of the output. Always `logs`. + Optional mask for inpainting. Contains `image_url` + (string, optional) and `file_id` (string, optional). - - `"logs"` + - `file_id: optional string` - - `Image object { type, url }` + File ID for the mask image. - The image output from the code interpreter. + - `image_url: optional string` - - `type: "image"` + Base64-encoded mask image. - The type of the output. Always `image`. + - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` - - `"image"` + The image generation model to use. Default: `gpt-image-1`. - - `url: string` + - `string` - The URL of the image output from the code interpreter. + - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` - - `status: "in_progress" or "completed" or "incomplete" or 2 more` + The image generation model to use. Default: `gpt-image-1`. - The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. + - `"gpt-image-1"` - - `"in_progress"` + - `"gpt-image-1-mini"` - - `"completed"` + - `"gpt-image-1.5"` - - `"incomplete"` + - `moderation: optional "auto" or "low"` - - `"interpreting"` + Moderation level for the generated image. Default: `auto`. - - `"failed"` + - `"auto"` - - `type: "code_interpreter_call"` + - `"low"` - The type of the code interpreter tool call. Always `code_interpreter_call`. + - `output_compression: optional number` - - `"code_interpreter_call"` + Compression level for the output image. Default: 100. - - `LocalShellCall object { id, action, call_id, 2 more }` + - `output_format: optional "png" or "webp" or "jpeg"` - A tool call to run a command on the local shell. + The output format of the generated image. One of `png`, `webp`, or + `jpeg`. Default: `png`. - - `id: string` + - `"png"` - The unique ID of the local shell call. + - `"webp"` - - `action: object { command, env, type, 3 more }` + - `"jpeg"` - Execute a shell command on the server. + - `partial_images: optional number` - - `command: array of string` + Number of partial images to generate in streaming mode, from 0 (default value) to 3. - The command to run. + - `quality: optional "low" or "medium" or "high" or "auto"` - - `env: map[string]` + The quality of the generated image. One of `low`, `medium`, `high`, + or `auto`. Default: `auto`. - Environment variables to set for the command. + - `"low"` - - `type: "exec"` + - `"medium"` - The type of the local shell action. Always `exec`. + - `"high"` - - `"exec"` + - `"auto"` - - `timeout_ms: optional number` + - `size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or "auto"` - Optional timeout in milliseconds for the command. + The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. - - `user: optional string` + - `string` - Optional user to run the command as. + - `"1024x1024" or "1024x1536" or "1536x1024" or "auto"` - - `working_directory: optional string` + The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. - Optional working directory to run the command in. + - `"1024x1024"` - - `call_id: string` + - `"1024x1536"` - The unique ID of the local shell tool call generated by the model. + - `"1536x1024"` - - `status: "in_progress" or "completed" or "incomplete"` + - `"auto"` - The status of the local shell call. + - `LocalShell object { type }` - - `"in_progress"` + A tool that allows the model to execute shell commands in a local environment. - - `"completed"` + - `type: "local_shell"` - - `"incomplete"` + The type of the local shell tool. Always `local_shell`. - - `type: "local_shell_call"` + - `"local_shell"` - The type of the local shell call. Always `local_shell_call`. + - `Shell object { type, environment }` - - `"local_shell_call"` + A tool that allows the model to execute shell commands. - - `LocalShellCallOutput object { id, output, type, status }` + - `type: "shell"` - The output of a local shell tool call. + The type of the shell tool. Always `shell`. - - `id: string` + - `"shell"` - The unique ID of the local shell tool call generated by the model. + - `environment: optional ContainerAuto or LocalEnvironment or ContainerReference` - - `output: string` + - `ContainerAuto object { type, file_ids, memory_limit, 2 more }` - A JSON string of the output of the local shell tool call. + - `LocalEnvironment object { type, skills }` - - `type: "local_shell_call_output"` + - `ContainerReference object { container_id, type }` - The type of the local shell tool call output. Always `local_shell_call_output`. + - `Custom object { name, type, defer_loading, 2 more }` - - `"local_shell_call_output"` + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) - - `status: optional "in_progress" or "completed" or "incomplete"` + - `name: string` - The status of the item. One of `in_progress`, `completed`, or `incomplete`. + The name of the custom tool, used to identify it in tool calls. - - `"in_progress"` + - `type: "custom"` - - `"completed"` + The type of the custom tool. Always `custom`. - - `"incomplete"` + - `"custom"` - - `ShellCall object { id, action, call_id, 4 more }` + - `defer_loading: optional boolean` - A tool call that executes one or more shell commands in a managed environment. + Whether this tool should be deferred and discovered via tool search. - - `id: string` + - `description: optional string` - The unique ID of the shell tool call. Populated when this item is returned via API. + Optional description of the custom tool, used to provide more context. - - `action: object { commands, max_output_length, timeout_ms }` + - `format: optional CustomToolInputFormat` - The shell commands and limits that describe how to run the tool call. + The input format for the custom tool. Default is unconstrained text. - - `commands: array of string` + - `Namespace object { description, name, tools, type }` - - `max_output_length: number` + Groups function/custom tools under a shared namespace. - Optional maximum number of characters to return from each command. + - `description: string` - - `timeout_ms: number` + A description of the namespace shown to the model. - Optional timeout in milliseconds for the commands. + - `name: string` - - `call_id: string` + The namespace name used in tool calls (for example, `crm`). - The unique ID of the shell tool call generated by the model. + - `tools: array of object { name, type, defer_loading, 3 more } or object { name, type, defer_loading, 2 more }` - - `environment: ResponseLocalEnvironment or ResponseContainerReference` + The function/custom tools available inside this namespace. - Represents the use of a local environment to perform shell actions. + - `Function object { name, type, defer_loading, 3 more }` - - `ResponseLocalEnvironment object { type }` + - `name: string` - Represents the use of a local environment to perform shell actions. + - `type: "function"` - - `type: "local"` + - `"function"` - The environment type. Always `local`. + - `defer_loading: optional boolean` - - `"local"` + Whether this function should be deferred and discovered via tool search. - - `ResponseContainerReference object { container_id, type }` + - `description: optional string` - Represents a container created with /v1/containers. + - `parameters: optional unknown` - - `container_id: string` + - `strict: optional boolean` - - `type: "container_reference"` + - `Custom object { name, type, defer_loading, 2 more }` - The environment type. Always `container_reference`. + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) - - `"container_reference"` + - `name: string` - - `status: "in_progress" or "completed" or "incomplete"` + The name of the custom tool, used to identify it in tool calls. - The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. + - `type: "custom"` - - `"in_progress"` + The type of the custom tool. Always `custom`. - - `"completed"` + - `"custom"` - - `"incomplete"` + - `defer_loading: optional boolean` - - `type: "shell_call"` + Whether this tool should be deferred and discovered via tool search. - The type of the item. Always `shell_call`. + - `description: optional string` - - `"shell_call"` + Optional description of the custom tool, used to provide more context. - - `created_by: optional string` + - `format: optional CustomToolInputFormat` - The ID of the entity that created this tool call. + The input format for the custom tool. Default is unconstrained text. - - `ShellCallOutput object { id, call_id, max_output_length, 4 more }` + - `type: "namespace"` - The output of a shell tool call that was emitted. + The type of the tool. Always `namespace`. - - `id: string` + - `"namespace"` - The unique ID of the shell call output. Populated when this item is returned via API. + - `ToolSearch object { type, description, execution, parameters }` - - `call_id: string` + Hosted or BYOT tool search configuration for deferred tools. - The unique ID of the shell tool call generated by the model. + - `type: "tool_search"` - - `max_output_length: number` + The type of the tool. Always `tool_search`. - The maximum length of the shell command output. This is generated by the model and should be passed back with the raw output. + - `"tool_search"` - - `output: array of object { outcome, stderr, stdout, created_by }` + - `description: optional string` - An array of shell call output contents + Description shown to the model for a client-executed tool search tool. - - `outcome: object { type } or object { exit_code, type }` + - `execution: optional "server" or "client"` - Represents either an exit outcome (with an exit code) or a timeout outcome for a shell call output chunk. + Whether tool search is executed by the server or by the client. - - `Timeout object { type }` + - `"server"` - Indicates that the shell call exceeded its configured time limit. + - `"client"` - - `type: "timeout"` + - `parameters: optional unknown` - The outcome type. Always `timeout`. + Parameter schema for a client-executed tool search tool. - - `"timeout"` + - `WebSearchPreview object { type, search_content_types, search_context_size, user_location }` - - `Exit object { exit_code, type }` + This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - Indicates that the shell commands finished and returned an exit code. + - `type: "web_search_preview" or "web_search_preview_2025_03_11"` - - `exit_code: number` + The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. - Exit code from the shell process. + - `"web_search_preview"` - - `type: "exit"` + - `"web_search_preview_2025_03_11"` - The outcome type. Always `exit`. + - `search_content_types: optional array of "text" or "image"` - - `"exit"` + - `"text"` - - `stderr: string` + - `"image"` - The standard error output that was captured. + - `search_context_size: optional "low" or "medium" or "high"` - - `stdout: string` + High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. - The standard output that was captured. + - `"low"` - - `created_by: optional string` + - `"medium"` - The identifier of the actor that created the item. + - `"high"` - - `status: "in_progress" or "completed" or "incomplete"` + - `user_location: optional object { type, city, country, 2 more }` - The status of the shell call output. One of `in_progress`, `completed`, or `incomplete`. + The user's location. - - `"in_progress"` + - `type: "approximate"` - - `"completed"` + The type of location approximation. Always `approximate`. - - `"incomplete"` + - `"approximate"` - - `type: "shell_call_output"` + - `city: optional string` - The type of the shell call output. Always `shell_call_output`. + Free text input for the city of the user, e.g. `San Francisco`. - - `"shell_call_output"` + - `country: optional string` - - `created_by: optional string` + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - The identifier of the actor that created the item. + - `region: optional string` - - `ApplyPatchCall object { id, call_id, operation, 3 more }` + Free text input for the region of the user, e.g. `California`. - A tool call that applies file diffs by creating, deleting, or updating files. + - `timezone: optional string` - - `id: string` + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - The unique ID of the apply patch tool call. Populated when this item is returned via API. + - `ApplyPatch object { type }` - - `call_id: string` + Allows the assistant to create, delete, or update files using unified diffs. - The unique ID of the apply patch tool call generated by the model. + - `type: "apply_patch"` - - `operation: object { diff, path, type } or object { path, type } or object { diff, path, type }` + The type of the tool. Always `apply_patch`. - One of the create_file, delete_file, or update_file operations applied via apply_patch. + - `"apply_patch"` - - `CreateFile object { diff, path, type }` + - `type: "additional_tools"` - Instruction describing how to create a file via the apply_patch tool. + The type of the item. Always `additional_tools`. - - `diff: string` + - `"additional_tools"` - Diff to apply. + - `Reasoning object { id, summary, type, 3 more }` - - `path: string` + 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). - Path of the file to create. + - `id: string` - - `type: "create_file"` + The unique identifier of the reasoning content. - Create a new file with the provided diff. + - `summary: array of SummaryTextContent` - - `"create_file"` + Reasoning summary content. - - `DeleteFile object { path, type }` + - `text: string` - Instruction describing how to delete a file via the apply_patch tool. + A summary of the reasoning output from the model so far. - - `path: string` + - `type: "summary_text"` - Path of the file to delete. + The type of the object. Always `summary_text`. - - `type: "delete_file"` + - `type: "reasoning"` - Delete the specified file. + The type of the object. Always `reasoning`. - - `"delete_file"` + - `"reasoning"` - - `UpdateFile object { diff, path, type }` + - `content: optional array of object { text, type }` - Instruction describing how to update a file via the apply_patch tool. + Reasoning text content. - - `diff: string` + - `text: string` - Diff to apply. + The reasoning text from the model. - - `path: string` + - `type: "reasoning_text"` - Path of the file to update. + The type of the reasoning text. Always `reasoning_text`. - - `type: "update_file"` + - `"reasoning_text"` - Update an existing file with the provided diff. + - `encrypted_content: optional string` - - `"update_file"` + The encrypted content of the reasoning item - populated when a response is + generated with `reasoning.encrypted_content` in the `include` parameter. - - `status: "in_progress" or "completed"` + - `status: optional "in_progress" or "completed" or "incomplete"` - The status of the apply patch tool call. One of `in_progress` or `completed`. + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - `"in_progress"` - `"completed"` - - `type: "apply_patch_call"` + - `"incomplete"` - The type of the item. Always `apply_patch_call`. + - `Compaction object { id, encrypted_content, type, created_by }` - - `"apply_patch_call"` + A compaction item generated by the [`v1/responses/compact` API](/docs/api-reference/responses/compact). - - `created_by: optional string` + - `id: string` - The ID of the entity that created this tool call. + The unique ID of the compaction item. - - `ApplyPatchCallOutput object { id, call_id, status, 3 more }` + - `encrypted_content: string` - The output emitted by an apply patch tool call. + The encrypted content that was produced by compaction. - - `id: string` + - `type: "compaction"` - The unique ID of the apply patch tool call output. Populated when this item is returned via API. + The type of the item. Always `compaction`. - - `call_id: string` + - `"compaction"` - The unique ID of the apply patch tool call generated by the model. + - `created_by: optional string` - - `status: "completed" or "failed"` + The identifier of the actor that created the item. - The status of the apply patch tool call output. One of `completed` or `failed`. + - `CodeInterpreterCall object { id, code, container_id, 3 more }` - - `"completed"` + A tool call to run code. - - `"failed"` + - `id: string` - - `type: "apply_patch_call_output"` + The unique ID of the code interpreter tool call. - The type of the item. Always `apply_patch_call_output`. + - `code: string` - - `"apply_patch_call_output"` + The code to run, or null if not available. - - `created_by: optional string` + - `container_id: string` - The ID of the entity that created this tool call output. + The ID of the container used to run the code. - - `output: optional string` + - `outputs: array of object { logs, type } or object { type, url }` - Optional textual output returned by the apply patch tool. + The outputs generated by the code interpreter, such as logs or images. + Can be null if no outputs are available. - - `McpListTools object { id, server_label, tools, 2 more }` + - `Logs object { logs, type }` - A list of tools available on an MCP server. + The logs output from the code interpreter. - - `id: string` + - `logs: string` - The unique ID of the list. + The logs output from the code interpreter. - - `server_label: string` + - `type: "logs"` - The label of the MCP server. + The type of the output. Always `logs`. - - `tools: array of object { input_schema, name, annotations, description }` + - `"logs"` - The tools available on the server. + - `Image object { type, url }` - - `input_schema: unknown` + The image output from the code interpreter. - The JSON schema describing the tool's input. + - `type: "image"` - - `name: string` + The type of the output. Always `image`. - The name of the tool. + - `"image"` - - `annotations: optional unknown` + - `url: string` - Additional annotations about the tool. + The URL of the image output from the code interpreter. - - `description: optional string` + - `status: "in_progress" or "completed" or "incomplete" or 2 more` - The description of the tool. + The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. - - `type: "mcp_list_tools"` + - `"in_progress"` - The type of the item. Always `mcp_list_tools`. + - `"completed"` - - `"mcp_list_tools"` + - `"incomplete"` - - `error: optional string` + - `"interpreting"` - Error message if the server could not list tools. + - `"failed"` - - `McpApprovalRequest object { id, arguments, name, 2 more }` + - `type: "code_interpreter_call"` - A request for human approval of a tool invocation. + The type of the code interpreter tool call. Always `code_interpreter_call`. + + - `"code_interpreter_call"` + + - `LocalShellCall object { id, action, call_id, 2 more }` + + A tool call to run a command on the local shell. - `id: string` - The unique ID of the approval request. + The unique ID of the local shell call. - - `arguments: string` + - `action: object { command, env, type, 3 more }` - A JSON string of arguments for the tool. + Execute a shell command on the server. - - `name: string` + - `command: array of string` - The name of the tool to run. + The command to run. - - `server_label: string` + - `env: map[string]` - The label of the MCP server making the request. + Environment variables to set for the command. - - `type: "mcp_approval_request"` + - `type: "exec"` - The type of the item. Always `mcp_approval_request`. + The type of the local shell action. Always `exec`. - - `"mcp_approval_request"` + - `"exec"` - - `McpApprovalResponse object { id, approval_request_id, approve, 2 more }` + - `timeout_ms: optional number` - A response to an MCP approval request. + Optional timeout in milliseconds for the command. - - `id: string` + - `user: optional string` - The unique ID of the approval response + Optional user to run the command as. - - `approval_request_id: string` + - `working_directory: optional string` - The ID of the approval request being answered. + Optional working directory to run the command in. - - `approve: boolean` + - `call_id: string` - Whether the request was approved. + The unique ID of the local shell tool call generated by the model. - - `type: "mcp_approval_response"` + - `status: "in_progress" or "completed" or "incomplete"` - The type of the item. Always `mcp_approval_response`. + The status of the local shell call. - - `"mcp_approval_response"` + - `"in_progress"` - - `reason: optional string` + - `"completed"` - Optional reason for the decision. + - `"incomplete"` - - `McpCall object { id, arguments, name, 6 more }` + - `type: "local_shell_call"` - An invocation of a tool on an MCP server. + The type of the local shell call. Always `local_shell_call`. - - `id: string` + - `"local_shell_call"` - The unique ID of the tool call. + - `LocalShellCallOutput object { id, output, type, status }` - - `arguments: string` + The output of a local shell tool call. - A JSON string of the arguments passed to the tool. + - `id: string` - - `name: string` + The unique ID of the local shell tool call generated by the model. - The name of the tool that was run. + - `output: string` - - `server_label: string` + A JSON string of the output of the local shell tool call. - The label of the MCP server running the tool. + - `type: "local_shell_call_output"` - - `type: "mcp_call"` + The type of the local shell tool call output. Always `local_shell_call_output`. - The type of the item. Always `mcp_call`. + - `"local_shell_call_output"` - - `"mcp_call"` + - `status: optional "in_progress" or "completed" or "incomplete"` - - `approval_request_id: optional string` + The status of the item. One of `in_progress`, `completed`, or `incomplete`. - Unique identifier for the MCP tool call approval request. - Include this value in a subsequent `mcp_approval_response` input to approve or reject the corresponding tool call. + - `"in_progress"` - - `error: optional string` + - `"completed"` - The error from the tool call, if any. + - `"incomplete"` - - `output: optional string` + - `ShellCall object { id, action, call_id, 4 more }` - The output from the tool call. + A tool call that executes one or more shell commands in a managed environment. - - `status: optional "in_progress" or "completed" or "incomplete" or 2 more` + - `id: string` - The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. + The unique ID of the shell tool call. Populated when this item is returned via API. - - `"in_progress"` + - `action: object { commands, max_output_length, timeout_ms }` - - `"completed"` + The shell commands and limits that describe how to run the tool call. - - `"incomplete"` + - `commands: array of string` - - `"calling"` + - `max_output_length: number` - - `"failed"` + Optional maximum number of characters to return from each command. - - `CustomToolCall object { call_id, input, name, 3 more }` + - `timeout_ms: number` - A call to a custom tool created by the model. + Optional timeout in milliseconds for the commands. - `call_id: string` - An identifier used to map this custom tool call to a tool call output. - - - `input: string` - - The input for the custom tool call generated by the model. + The unique ID of the shell tool call generated by the model. - - `name: string` + - `environment: ResponseLocalEnvironment or ResponseContainerReference` - The name of the custom tool being called. + Represents the use of a local environment to perform shell actions. - - `type: "custom_tool_call"` + - `ResponseLocalEnvironment object { type }` - The type of the custom tool call. Always `custom_tool_call`. + Represents the use of a local environment to perform shell actions. - - `"custom_tool_call"` + - `type: "local"` - - `id: optional string` + The environment type. Always `local`. - The unique ID of the custom tool call in the OpenAI platform. + - `"local"` - - `namespace: optional string` + - `ResponseContainerReference object { container_id, type }` - The namespace of the custom tool being called. + Represents a container created with /v1/containers. - - `CustomToolCallOutput object { call_id, output, type, id }` + - `container_id: string` - The output of a custom tool call from your code, being sent back to the model. + - `type: "container_reference"` - - `call_id: string` + The environment type. Always `container_reference`. - The call ID, used to map this custom tool call output to a custom tool call. + - `"container_reference"` - - `output: string or array of ResponseInputText or ResponseInputImage or ResponseInputFile` + - `status: "in_progress" or "completed" or "incomplete"` - The output from the custom tool call generated by your code. - Can be a string or an list of output content. + The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. - - `StringOutput = string` + - `"in_progress"` - A string of the output of the custom tool call. + - `"completed"` - - `OutputContentList = array of ResponseInputText or ResponseInputImage or ResponseInputFile` + - `"incomplete"` - Text, image, or file output of the custom tool call. + - `type: "shell_call"` - - `ResponseInputText object { text, type }` + The type of the item. Always `shell_call`. - A text input to the model. + - `"shell_call"` - - `ResponseInputImage object { detail, type, file_id, image_url }` + - `created_by: optional string` - An image input to the model. Learn about [image inputs](/docs/guides/vision). + The ID of the entity that created this tool call. - - `ResponseInputFile object { type, detail, file_data, 3 more }` + - `ShellCallOutput object { id, call_id, max_output_length, 4 more }` - A file input to the model. + The output of a shell tool call that was emitted. - - `type: "custom_tool_call_output"` + - `id: string` - The type of the custom tool call output. Always `custom_tool_call_output`. + The unique ID of the shell call output. Populated when this item is returned via API. - - `"custom_tool_call_output"` + - `call_id: string` - - `id: optional string` + The unique ID of the shell tool call generated by the model. - The unique ID of the custom tool call output in the OpenAI platform. + - `max_output_length: number` - - `first_id: string` + The maximum length of the shell command output. This is generated by the model and should be passed back with the raw output. - The ID of the first item in the list. + - `output: array of object { outcome, stderr, stdout, created_by }` - - `has_more: boolean` + An array of shell call output contents - Whether there are more items available. + - `outcome: object { type } or object { exit_code, type }` - - `last_id: string` + Represents either an exit outcome (with an exit code) or a timeout outcome for a shell call output chunk. - The ID of the last item in the list. + - `Timeout object { type }` - - `object: "list"` + Indicates that the shell call exceeded its configured time limit. - The type of object returned, must be `list`. + - `type: "timeout"` - - `"list"` + The outcome type. Always `timeout`. -### Example + - `"timeout"` -```http -curl https://api.openai.com/v1/conversations/$CONVERSATION_ID/items \ - -H 'Content-Type: application/json' \ - -H "Authorization: Bearer $OPENAI_API_KEY" \ - -d '{ - "items": [ - { - "content": "string", - "role": "user", - "type": "message" - } - ] - }' -``` + - `Exit object { exit_code, type }` -#### Response + Indicates that the shell commands finished and returned an exit code. -```json -{ - "data": [ - { - "id": "id", - "content": [ - { - "text": "text", - "type": "input_text" - } - ], - "role": "unknown", - "status": "in_progress", - "type": "message", - "phase": "commentary" - } - ], - "first_id": "first_id", - "has_more": true, - "last_id": "last_id", - "object": "list" -} -``` + - `exit_code: number` -### Example + Exit code from the shell process. -```http -curl https://api.openai.com/v1/conversations/conv_123/items \ - -H "Content-Type: application/json" \ - -H "Authorization: Bearer $OPENAI_API_KEY" \ - -d '{ - "items": [ - { - "type": "message", - "role": "user", - "content": [ - {"type": "input_text", "text": "Hello!"} - ] - }, - { - "type": "message", - "role": "user", - "content": [ - {"type": "input_text", "text": "How are you?"} - ] - } - ] - }' -``` + - `type: "exit"` -#### Response + The outcome type. Always `exit`. -```json -{ - "object": "list", - "data": [ - { - "type": "message", - "id": "msg_abc", - "status": "completed", - "role": "user", - "content": [ - {"type": "input_text", "text": "Hello!"} - ] - }, - { - "type": "message", - "id": "msg_def", - "status": "completed", - "role": "user", - "content": [ - {"type": "input_text", "text": "How are you?"} - ] - } - ], - "first_id": "msg_abc", - "last_id": "msg_def", - "has_more": false -} -``` + - `"exit"` -## List items + - `stderr: string` -**get** `/conversations/{conversation_id}/items` + The standard error output that was captured. -List all items for a conversation with the given ID. + - `stdout: string` -### Path Parameters + The standard output that was captured. -- `conversation_id: string` + - `created_by: optional string` -### Query Parameters + The identifier of the actor that created the item. -- `after: optional string` + - `status: "in_progress" or "completed" or "incomplete"` - An item ID to list items after, used in pagination. + The status of the shell call output. One of `in_progress`, `completed`, or `incomplete`. -- `include: optional array of ResponseIncludable` + - `"in_progress"` - Specify additional output data to include in the model response. Currently supported values are: + - `"completed"` - - `web_search_call.action.sources`: Include the sources of the web search tool call. - - `code_interpreter_call.outputs`: Includes the outputs of python code execution in code interpreter tool call items. - - `computer_call_output.output.image_url`: Include image urls from the computer call output. - - `file_search_call.results`: Include the search results of the file search tool call. - - `message.input_image.image_url`: Include image urls from the input message. - - `message.output_text.logprobs`: Include logprobs with assistant messages. - - `reasoning.encrypted_content`: Includes an encrypted version of reasoning tokens in reasoning item outputs. This enables reasoning items to be used in multi-turn conversations when using the Responses API statelessly (like when the `store` parameter is set to `false`, or when an organization is enrolled in the zero data retention program). + - `"incomplete"` - - `"file_search_call.results"` + - `type: "shell_call_output"` - - `"web_search_call.results"` + The type of the shell call output. Always `shell_call_output`. - - `"web_search_call.action.sources"` + - `"shell_call_output"` - - `"message.input_image.image_url"` + - `created_by: optional string` - - `"computer_call_output.output.image_url"` + The identifier of the actor that created the item. - - `"code_interpreter_call.outputs"` + - `ApplyPatchCall object { id, call_id, operation, 3 more }` - - `"reasoning.encrypted_content"` + A tool call that applies file diffs by creating, deleting, or updating files. - - `"message.output_text.logprobs"` + - `id: string` -- `limit: optional number` + The unique ID of the apply patch tool call. Populated when this item is returned via API. - A limit on the number of objects to be returned. Limit can range between - 1 and 100, and the default is 20. + - `call_id: string` -- `order: optional "asc" or "desc"` + The unique ID of the apply patch tool call generated by the model. - The order to return the input items in. Default is `desc`. + - `operation: object { diff, path, type } or object { path, type } or object { diff, path, type }` - - `asc`: Return the input items in ascending order. - - `desc`: Return the input items in descending order. + One of the create_file, delete_file, or update_file operations applied via apply_patch. - - `"asc"` + - `CreateFile object { diff, path, type }` - - `"desc"` + Instruction describing how to create a file via the apply_patch tool. -### Returns + - `diff: string` -- `ConversationItemList object { data, first_id, has_more, 2 more }` + Diff to apply. - A list of Conversation items. + - `path: string` - - `data: array of ConversationItem` + Path of the file to create. - A list of conversation items. + - `type: "create_file"` - - `Message object { id, content, role, 3 more }` + Create a new file with the provided diff. - A message to or from the model. + - `"create_file"` - - `id: string` + - `DeleteFile object { path, type }` - The unique ID of the message. + Instruction describing how to delete a file via the apply_patch tool. - - `content: array of ResponseInputText or ResponseOutputText or TextContent or 6 more` + - `path: string` - The content of the message + Path of the file to delete. - - `ResponseInputText object { text, type }` + - `type: "delete_file"` - A text input to the model. + Delete the specified file. - - `text: string` + - `"delete_file"` - The text input to the model. + - `UpdateFile object { diff, path, type }` - - `type: "input_text"` + Instruction describing how to update a file via the apply_patch tool. - The type of the input item. Always `input_text`. + - `diff: string` - - `"input_text"` + Diff to apply. - - `ResponseOutputText object { annotations, logprobs, text, type }` + - `path: string` - A text output from the model. + Path of the file to update. - - `annotations: array of object { file_id, filename, index, type } or object { end_index, start_index, title, 2 more } or object { container_id, end_index, file_id, 3 more } or object { file_id, index, type }` + - `type: "update_file"` - The annotations of the text output. + Update an existing file with the provided diff. - - `FileCitation object { file_id, filename, index, type }` + - `"update_file"` - A citation to a file. + - `status: "in_progress" or "completed"` - - `file_id: string` + The status of the apply patch tool call. One of `in_progress` or `completed`. - The ID of the file. + - `"in_progress"` - - `filename: string` + - `"completed"` - The filename of the file cited. + - `type: "apply_patch_call"` - - `index: number` + The type of the item. Always `apply_patch_call`. - The index of the file in the list of files. + - `"apply_patch_call"` - - `type: "file_citation"` + - `created_by: optional string` - The type of the file citation. Always `file_citation`. + The ID of the entity that created this tool call. - - `"file_citation"` + - `ApplyPatchCallOutput object { id, call_id, status, 3 more }` - - `URLCitation object { end_index, start_index, title, 2 more }` + The output emitted by an apply patch tool call. - A citation for a web resource used to generate a model response. + - `id: string` - - `end_index: number` + The unique ID of the apply patch tool call output. Populated when this item is returned via API. - The index of the last character of the URL citation in the message. + - `call_id: string` - - `start_index: number` + The unique ID of the apply patch tool call generated by the model. - The index of the first character of the URL citation in the message. + - `status: "completed" or "failed"` - - `title: string` + The status of the apply patch tool call output. One of `completed` or `failed`. - The title of the web resource. + - `"completed"` - - `type: "url_citation"` + - `"failed"` - The type of the URL citation. Always `url_citation`. + - `type: "apply_patch_call_output"` - - `"url_citation"` + The type of the item. Always `apply_patch_call_output`. - - `url: string` + - `"apply_patch_call_output"` - The URL of the web resource. + - `created_by: optional string` - - `ContainerFileCitation object { container_id, end_index, file_id, 3 more }` + The ID of the entity that created this tool call output. - A citation for a container file used to generate a model response. + - `output: optional string` - - `container_id: string` + Optional textual output returned by the apply patch tool. - The ID of the container file. + - `McpListTools object { id, server_label, tools, 2 more }` - - `end_index: number` + A list of tools available on an MCP server. - The index of the last character of the container file citation in the message. + - `id: string` - - `file_id: string` + The unique ID of the list. - The ID of the file. + - `server_label: string` - - `filename: string` + The label of the MCP server. - The filename of the container file cited. + - `tools: array of object { input_schema, name, annotations, description }` - - `start_index: number` + The tools available on the server. - The index of the first character of the container file citation in the message. + - `input_schema: unknown` - - `type: "container_file_citation"` + The JSON schema describing the tool's input. - The type of the container file citation. Always `container_file_citation`. + - `name: string` - - `"container_file_citation"` + The name of the tool. - - `FilePath object { file_id, index, type }` + - `annotations: optional unknown` - A path to a file. + Additional annotations about the tool. - - `file_id: string` + - `description: optional string` - The ID of the file. + The description of the tool. - - `index: number` + - `type: "mcp_list_tools"` - The index of the file in the list of files. + The type of the item. Always `mcp_list_tools`. - - `type: "file_path"` + - `"mcp_list_tools"` - The type of the file path. Always `file_path`. + - `error: optional string` - - `"file_path"` + Error message if the server could not list tools. - - `logprobs: array of object { token, bytes, logprob, top_logprobs }` + - `McpApprovalRequest object { id, arguments, name, 2 more }` - - `token: string` + A request for human approval of a tool invocation. - - `bytes: array of number` + - `id: string` - - `logprob: number` + The unique ID of the approval request. - - `top_logprobs: array of object { token, bytes, logprob }` + - `arguments: string` - - `token: string` + A JSON string of arguments for the tool. - - `bytes: array of number` + - `name: string` - - `logprob: number` + The name of the tool to run. - - `text: string` + - `server_label: string` - The text output from the model. + The label of the MCP server making the request. - - `type: "output_text"` + - `type: "mcp_approval_request"` - The type of the output text. Always `output_text`. + The type of the item. Always `mcp_approval_request`. - - `"output_text"` + - `"mcp_approval_request"` - - `TextContent object { text, type }` + - `McpApprovalResponse object { id, approval_request_id, approve, 2 more }` - A text content. + A response to an MCP approval request. - - `text: string` + - `id: string` - - `type: "text"` + The unique ID of the approval response - - `"text"` + - `approval_request_id: string` - - `SummaryTextContent object { text, type }` + The ID of the approval request being answered. - A summary text from the model. + - `approve: boolean` - - `text: string` + Whether the request was approved. - A summary of the reasoning output from the model so far. + - `type: "mcp_approval_response"` - - `type: "summary_text"` + The type of the item. Always `mcp_approval_response`. - The type of the object. Always `summary_text`. + - `"mcp_approval_response"` - - `"summary_text"` + - `reason: optional string` - - `ReasoningText object { text, type }` + Optional reason for the decision. - Reasoning text from the model. + - `McpCall object { id, arguments, name, 6 more }` - - `text: string` + An invocation of a tool on an MCP server. - The reasoning text from the model. + - `id: string` - - `type: "reasoning_text"` + The unique ID of the tool call. - The type of the reasoning text. Always `reasoning_text`. + - `arguments: string` - - `"reasoning_text"` + A JSON string of the arguments passed to the tool. - - `ResponseOutputRefusal object { refusal, type }` + - `name: string` - A refusal from the model. + The name of the tool that was run. - - `refusal: string` + - `server_label: string` - The refusal explanation from the model. + The label of the MCP server running the tool. - - `type: "refusal"` + - `type: "mcp_call"` - The type of the refusal. Always `refusal`. + The type of the item. Always `mcp_call`. - - `"refusal"` + - `"mcp_call"` - - `ResponseInputImage object { detail, type, file_id, image_url }` + - `approval_request_id: optional string` - An image input to the model. Learn about [image inputs](/docs/guides/vision). + Unique identifier for the MCP tool call approval request. + Include this value in a subsequent `mcp_approval_response` input to approve or reject the corresponding tool call. - - `detail: "low" or "high" or "auto" or "original"` + - `error: optional string` - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + The error from the tool call, if any. - - `"low"` + - `output: optional string` - - `"high"` + The output from the tool call. - - `"auto"` + - `status: optional "in_progress" or "completed" or "incomplete" or 2 more` - - `"original"` + The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. - - `type: "input_image"` + - `"in_progress"` - The type of the input item. Always `input_image`. + - `"completed"` - - `"input_image"` + - `"incomplete"` - - `file_id: optional string` + - `"calling"` - The ID of the file to be sent to the model. + - `"failed"` - - `image_url: optional string` + - `CustomToolCall object { call_id, input, name, 3 more }` - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + A call to a custom tool created by the model. - - `ComputerScreenshotContent object { detail, file_id, image_url, type }` + - `call_id: string` - A screenshot of a computer. + An identifier used to map this custom tool call to a tool call output. - - `detail: "low" or "high" or "auto" or "original"` + - `input: string` - The detail level of the screenshot image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + The input for the custom tool call generated by the model. - - `"low"` + - `name: string` - - `"high"` + The name of the custom tool being called. - - `"auto"` + - `type: "custom_tool_call"` - - `"original"` + The type of the custom tool call. Always `custom_tool_call`. - - `file_id: string` + - `"custom_tool_call"` - The identifier of an uploaded file that contains the screenshot. + - `id: optional string` - - `image_url: string` + The unique ID of the custom tool call in the OpenAI platform. - The URL of the screenshot image. + - `namespace: optional string` - - `type: "computer_screenshot"` + The namespace of the custom tool being called. - Specifies the event type. For a computer screenshot, this property is always set to `computer_screenshot`. + - `CustomToolCallOutput object { call_id, output, type, id }` - - `"computer_screenshot"` + The output of a custom tool call from your code, being sent back to the model. - - `ResponseInputFile object { type, detail, file_data, 3 more }` + - `call_id: string` - A file input to the model. + The call ID, used to map this custom tool call output to a custom tool call. - - `type: "input_file"` + - `output: string or array of ResponseInputText or ResponseInputImage or ResponseInputFile` - The type of the input item. Always `input_file`. + The output from the custom tool call generated by your code. + Can be a string or an list of output content. - - `"input_file"` + - `StringOutput = string` - - `detail: optional "low" or "high"` + A string of the output of the custom tool call. - The detail level of the file to be sent to the model. Use `low` for the default rendering behavior, or `high` to render the file at higher quality. Defaults to `low`. + - `OutputContentList = array of ResponseInputText or ResponseInputImage or ResponseInputFile` - - `"low"` + Text, image, or file output of the custom tool call. - - `"high"` + - `ResponseInputText object { text, type }` - - `file_data: optional string` + A text input to the model. - The content of the file to be sent to the model. + - `ResponseInputImage object { detail, type, file_id, image_url }` - - `file_id: optional string` + An image input to the model. Learn about [image inputs](/docs/guides/vision). - The ID of the file to be sent to the model. + - `ResponseInputFile object { type, detail, file_data, 3 more }` - - `file_url: optional string` + A file input to the model. - The URL of the file to be sent to the model. + - `type: "custom_tool_call_output"` - - `filename: optional string` + The type of the custom tool call output. Always `custom_tool_call_output`. - The name of the file to be sent to the model. + - `"custom_tool_call_output"` - - `role: "unknown" or "user" or "assistant" or 5 more` + - `id: optional string` - The role of the message. One of `unknown`, `user`, `assistant`, `system`, `critic`, `discriminator`, `developer`, or `tool`. + The unique ID of the custom tool call output in the OpenAI platform. - - `"unknown"` + - `first_id: string` - - `"user"` + The ID of the first item in the list. - - `"assistant"` + - `has_more: boolean` - - `"system"` + Whether there are more items available. - - `"critic"` + - `last_id: string` - - `"discriminator"` + The ID of the last item in the list. - - `"developer"` + - `object: "list"` - - `"tool"` + The type of object returned, must be `list`. - - `status: "in_progress" or "completed" or "incomplete"` + - `"list"` - The status of item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. +### Example - - `"in_progress"` +```http +curl https://api.openai.com/v1/conversations/$CONVERSATION_ID/items \ + -H "Authorization: Bearer $OPENAI_API_KEY" +``` - - `"completed"` +#### Response - - `"incomplete"` +```json +{ + "data": [ + { + "id": "id", + "content": [ + { + "text": "text", + "type": "input_text" + } + ], + "role": "unknown", + "status": "in_progress", + "type": "message", + "phase": "commentary" + } + ], + "first_id": "first_id", + "has_more": true, + "last_id": "last_id", + "object": "list" +} +``` - - `type: "message"` +### Example - The type of the message. Always set to `message`. +```http +curl "https://api.openai.com/v1/conversations/conv_123/items?limit=10" \ + -H "Authorization: Bearer $OPENAI_API_KEY" +``` - - `"message"` +#### Response - - `phase: optional "commentary" or "final_answer"` +```json +{ + "object": "list", + "data": [ + { + "type": "message", + "id": "msg_abc", + "status": "completed", + "role": "user", + "content": [ + {"type": "input_text", "text": "Hello!"} + ] + } + ], + "first_id": "msg_abc", + "last_id": "msg_abc", + "has_more": false +} +``` - Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend phase on all assistant messages — dropping it can degrade performance. Not used for user messages. +## Retrieve an item - - `"commentary"` +**get** `/conversations/{conversation_id}/items/{item_id}` - - `"final_answer"` +Get a single item from a conversation with the given IDs. - - `FunctionCall object { id, arguments, call_id, 5 more }` +### Path Parameters - - `id: string` +- `conversation_id: string` - The unique ID of the function tool call. +- `item_id: string` - - `arguments: string` +### Query Parameters - A JSON string of the arguments to pass to the function. +- `include: optional array of ResponseIncludable` - - `call_id: string` + 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. - The unique ID of the function tool call generated by the model. + - `"file_search_call.results"` - - `name: string` + - `"web_search_call.results"` - The name of the function to run. + - `"web_search_call.action.sources"` - - `status: "in_progress" or "completed" or "incomplete"` + - `"message.input_image.image_url"` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `"computer_call_output.output.image_url"` - - `"in_progress"` + - `"code_interpreter_call.outputs"` - - `"completed"` + - `"reasoning.encrypted_content"` - - `"incomplete"` + - `"message.output_text.logprobs"` - - `type: "function_call"` +### Returns - The type of the function tool call. Always `function_call`. +- `ConversationItem = Message or object { id, arguments, call_id, 5 more } or object { id, call_id, output, 3 more } or 23 more` - - `"function_call"` + 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). - - `created_by: optional string` + - `Message object { id, content, role, 3 more }` - The identifier of the actor that created the item. + A message to or from the model. - - `namespace: optional string` + - `id: string` - The namespace of the function to run. + The unique ID of the message. - - `FunctionCallOutput object { id, call_id, output, 3 more }` + - `content: array of ResponseInputText or ResponseOutputText or TextContent or 6 more` - - `id: string` + The content of the message - The unique ID of the function call tool output. + - `ResponseInputText object { text, type }` - - `call_id: string` + A text input to the model. - The unique ID of the function tool call generated by the model. + - `text: string` - - `output: string or array of ResponseInputText or ResponseInputImage or ResponseInputFile` + The text input to the model. - The output from the function call generated by your code. - Can be a string or an list of output content. + - `type: "input_text"` - - `StringOutput = string` + The type of the input item. Always `input_text`. - A string of the output of the function call. + - `"input_text"` - - `OutputContentList = array of ResponseInputText or ResponseInputImage or ResponseInputFile` + - `ResponseOutputText object { annotations, logprobs, text, type }` - Text, image, or file output of the function call. + A text output from the model. - - `ResponseInputText object { text, type }` + - `annotations: array of object { file_id, filename, index, type } or object { end_index, start_index, title, 2 more } or object { container_id, end_index, file_id, 3 more } or object { file_id, index, type }` - A text input to the model. + The annotations of the text output. - - `ResponseInputImage object { detail, type, file_id, image_url }` + - `FileCitation object { file_id, filename, index, type }` - An image input to the model. Learn about [image inputs](/docs/guides/vision). + A citation to a file. - - `ResponseInputFile object { type, detail, file_data, 3 more }` + - `file_id: string` - A file input to the model. + The ID of the file. - - `status: "in_progress" or "completed" or "incomplete"` + - `filename: string` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + The filename of the file cited. - - `"in_progress"` + - `index: number` - - `"completed"` + The index of the file in the list of files. - - `"incomplete"` + - `type: "file_citation"` - - `type: "function_call_output"` + The type of the file citation. Always `file_citation`. - The type of the function tool call output. Always `function_call_output`. + - `"file_citation"` - - `"function_call_output"` + - `URLCitation object { end_index, start_index, title, 2 more }` - - `created_by: optional string` + A citation for a web resource used to generate a model response. - The identifier of the actor that created the item. + - `end_index: number` - - `FileSearchCall object { id, queries, status, 2 more }` + The index of the last character of the URL citation in the message. - The results of a file search tool call. See the - [file search guide](/docs/guides/tools-file-search) for more information. + - `start_index: number` - - `id: string` + The index of the first character of the URL citation in the message. - The unique ID of the file search tool call. + - `title: string` - - `queries: array of string` + The title of the web resource. - The queries used to search for files. + - `type: "url_citation"` - - `status: "in_progress" or "searching" or "completed" or 2 more` + The type of the URL citation. Always `url_citation`. - The status of the file search tool call. One of `in_progress`, - `searching`, `incomplete` or `failed`, + - `"url_citation"` - - `"in_progress"` + - `url: string` - - `"searching"` + The URL of the web resource. - - `"completed"` + - `ContainerFileCitation object { container_id, end_index, file_id, 3 more }` - - `"incomplete"` + A citation for a container file used to generate a model response. - - `"failed"` + - `container_id: string` - - `type: "file_search_call"` + The ID of the container file. - The type of the file search tool call. Always `file_search_call`. + - `end_index: number` - - `"file_search_call"` + The index of the last character of the container file citation in the message. - - `results: optional array of object { attributes, file_id, filename, 2 more }` + - `file_id: string` - The results of the file search tool call. + The ID of the file. - - `attributes: optional map[string or number or boolean]` + - `filename: string` - Set of 16 key-value pairs that can be attached to an object. This can be - useful for storing additional information about the object in a structured - format, and querying for objects via API or the dashboard. Keys are strings - with a maximum length of 64 characters. Values are strings with a maximum - length of 512 characters, booleans, or numbers. + The filename of the container file cited. - - `string` + - `start_index: number` - - `number` + The index of the first character of the container file citation in the message. - - `boolean` + - `type: "container_file_citation"` - - `file_id: optional string` + The type of the container file citation. Always `container_file_citation`. - The unique ID of the file. + - `"container_file_citation"` - - `filename: optional string` + - `FilePath object { file_id, index, type }` - The name of the file. + A path to a file. - - `score: optional number` + - `file_id: string` - The relevance score of the file - a value between 0 and 1. + The ID of the file. - - `text: optional string` + - `index: number` - The text that was retrieved from the file. + The index of the file in the list of files. - - `WebSearchCall object { id, action, status, type }` + - `type: "file_path"` - The results of a web search tool call. See the - [web search guide](/docs/guides/tools-web-search) for more information. + The type of the file path. Always `file_path`. - - `id: string` + - `"file_path"` - The unique ID of the web search tool call. + - `logprobs: array of object { token, bytes, logprob, top_logprobs }` - - `action: object { query, type, queries, sources } or object { type, url } or object { pattern, type, url }` + - `token: string` - An object describing the specific action taken in this web search call. - Includes details on how the model used the web (search, open_page, find_in_page). + - `bytes: array of number` - - `Search object { query, type, queries, sources }` + - `logprob: number` - Action type "search" - Performs a web search query. + - `top_logprobs: array of object { token, bytes, logprob }` - - `query: string` + - `token: string` - [DEPRECATED] The search query. + - `bytes: array of number` - - `type: "search"` + - `logprob: number` - The action type. + - `text: string` - - `"search"` + The text output from the model. - - `queries: optional array of string` + - `type: "output_text"` - The search queries. + The type of the output text. Always `output_text`. - - `sources: optional array of object { type, url }` + - `"output_text"` - The sources used in the search. + - `TextContent object { text, type }` - - `type: "url"` + A text content. - The type of source. Always `url`. + - `text: string` - - `"url"` + - `type: "text"` - - `url: string` + - `"text"` - The URL of the source. + - `SummaryTextContent object { text, type }` - - `OpenPage object { type, url }` + A summary text from the model. - Action type "open_page" - Opens a specific URL from search results. + - `text: string` - - `type: "open_page"` + A summary of the reasoning output from the model so far. - The action type. + - `type: "summary_text"` - - `"open_page"` + The type of the object. Always `summary_text`. - - `url: optional string` + - `"summary_text"` - The URL opened by the model. + - `ReasoningText object { text, type }` - - `FindInPage object { pattern, type, url }` + Reasoning text from the model. - Action type "find_in_page": Searches for a pattern within a loaded page. + - `text: string` - - `pattern: string` + The reasoning text from the model. - The pattern or text to search for within the page. + - `type: "reasoning_text"` - - `type: "find_in_page"` + The type of the reasoning text. Always `reasoning_text`. - The action type. + - `"reasoning_text"` - - `"find_in_page"` + - `ResponseOutputRefusal object { refusal, type }` - - `url: string` + A refusal from the model. - The URL of the page searched for the pattern. + - `refusal: string` - - `status: "in_progress" or "searching" or "completed" or "failed"` + The refusal explanation from the model. - The status of the web search tool call. + - `type: "refusal"` - - `"in_progress"` + The type of the refusal. Always `refusal`. - - `"searching"` + - `"refusal"` - - `"completed"` + - `ResponseInputImage object { detail, type, file_id, image_url }` - - `"failed"` + An image input to the model. Learn about [image inputs](/docs/guides/vision). - - `type: "web_search_call"` + - `detail: "low" or "high" or "auto" or "original"` - The type of the web search tool call. Always `web_search_call`. + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - - `"web_search_call"` + - `"low"` - - `ImageGenerationCall object { id, result, status, type }` + - `"high"` - An image generation request made by the model. + - `"auto"` - - `id: string` + - `"original"` - The unique ID of the image generation call. + - `type: "input_image"` - - `result: string` + The type of the input item. Always `input_image`. - The generated image encoded in base64. + - `"input_image"` - - `status: "in_progress" or "completed" or "generating" or "failed"` + - `file_id: optional string` - The status of the image generation call. + The ID of the file to be sent to the model. - - `"in_progress"` + - `image_url: optional string` - - `"completed"` + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - - `"generating"` + - `ComputerScreenshotContent object { detail, file_id, image_url, type }` - - `"failed"` + A screenshot of a computer. - - `type: "image_generation_call"` + - `detail: "low" or "high" or "auto" or "original"` - The type of the image generation call. Always `image_generation_call`. + The detail level of the screenshot image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - - `"image_generation_call"` + - `"low"` - - `ComputerCall object { id, call_id, pending_safety_checks, 4 more }` + - `"high"` - A tool call to a computer use tool. See the - [computer use guide](/docs/guides/tools-computer-use) for more information. + - `"auto"` - - `id: string` + - `"original"` - The unique ID of the computer call. + - `file_id: string` - - `call_id: string` + The identifier of an uploaded file that contains the screenshot. - An identifier used when responding to the tool call with output. + - `image_url: string` - - `pending_safety_checks: array of object { id, code, message }` + The URL of the screenshot image. - The pending safety checks for the computer call. + - `type: "computer_screenshot"` - - `id: string` + Specifies the event type. For a computer screenshot, this property is always set to `computer_screenshot`. - The ID of the pending safety check. + - `"computer_screenshot"` - - `code: optional string` + - `ResponseInputFile object { type, detail, file_data, 3 more }` - The type of the pending safety check. + A file input to the model. - - `message: optional string` + - `type: "input_file"` - Details about the pending safety check. + The type of the input item. Always `input_file`. - - `status: "in_progress" or "completed" or "incomplete"` + - `"input_file"` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `detail: optional "low" or "high"` - - `"in_progress"` + 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`. - - `"completed"` + - `"low"` - - `"incomplete"` + - `"high"` - - `type: "computer_call"` + - `file_data: optional string` - The type of the computer call. Always `computer_call`. + The content of the file to be sent to the model. - - `"computer_call"` + - `file_id: optional string` - - `action: optional ComputerAction` + The ID of the file to be sent to the model. - A click action. + - `file_url: optional string` - - `Click object { button, type, x, 2 more }` + The URL of the file to be sent to the model. - A click action. + - `filename: optional string` - - `button: "left" or "right" or "wheel" or 2 more` + The name of the file to be sent to the model. - Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. + - `role: "unknown" or "user" or "assistant" or 5 more` - - `"left"` + The role of the message. One of `unknown`, `user`, `assistant`, `system`, `critic`, `discriminator`, `developer`, or `tool`. - - `"right"` + - `"unknown"` - - `"wheel"` + - `"user"` - - `"back"` + - `"assistant"` - - `"forward"` + - `"system"` - - `type: "click"` + - `"critic"` - Specifies the event type. For a click action, this property is always `click`. + - `"discriminator"` - - `"click"` + - `"developer"` - - `x: number` + - `"tool"` - The x-coordinate where the click occurred. + - `status: "in_progress" or "completed" or "incomplete"` - - `y: number` + The status of item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. - The y-coordinate where the click occurred. + - `"in_progress"` - - `keys: optional array of string` + - `"completed"` - The keys being held while clicking. + - `"incomplete"` - - `DoubleClick object { keys, type, x, y }` + - `type: "message"` - A double click action. + The type of the message. Always set to `message`. - - `keys: array of string` + - `"message"` - The keys being held while double-clicking. + - `phase: optional "commentary" or "final_answer"` - - `type: "double_click"` + Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend phase on all assistant messages — dropping it can degrade performance. Not used for user messages. - Specifies the event type. For a double click action, this property is always set to `double_click`. + - `"commentary"` - - `"double_click"` + - `"final_answer"` - - `x: number` + - `FunctionCall object { id, arguments, call_id, 5 more }` - The x-coordinate where the double click occurred. + - `id: string` - - `y: number` + The unique ID of the function tool call. - The y-coordinate where the double click occurred. + - `arguments: string` - - `Drag object { path, type, keys }` + A JSON string of the arguments to pass to the function. - A drag action. + - `call_id: string` - - `path: array of object { x, y }` + The unique ID of the function tool call generated by the model. - An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg + - `name: string` - ``` - [ - { x: 100, y: 200 }, - { x: 200, y: 300 } - ] - ``` + The name of the function to run. - - `x: number` + - `status: "in_progress" or "completed" or "incomplete"` - The x-coordinate. + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `y: number` + - `"in_progress"` - The y-coordinate. + - `"completed"` - - `type: "drag"` + - `"incomplete"` - Specifies the event type. For a drag action, this property is always set to `drag`. + - `type: "function_call"` - - `"drag"` + The type of the function tool call. Always `function_call`. - - `keys: optional array of string` + - `"function_call"` - The keys being held while dragging the mouse. + - `created_by: optional string` - - `Keypress object { keys, type }` + The identifier of the actor that created the item. - A collection of keypresses the model would like to perform. + - `namespace: optional string` - - `keys: array of string` + The namespace of the function to run. - The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. + - `FunctionCallOutput object { id, call_id, output, 3 more }` - - `type: "keypress"` + - `id: string` - Specifies the event type. For a keypress action, this property is always set to `keypress`. + The unique ID of the function call tool output. - - `"keypress"` + - `call_id: string` - - `Move object { type, x, y, keys }` + The unique ID of the function tool call generated by the model. - A mouse move action. + - `output: string or array of ResponseInputText or ResponseInputImage or ResponseInputFile` - - `type: "move"` + The output from the function call generated by your code. + Can be a string or an list of output content. - Specifies the event type. For a move action, this property is always set to `move`. + - `StringOutput = string` - - `"move"` + A string of the output of the function call. - - `x: number` + - `OutputContentList = array of ResponseInputText or ResponseInputImage or ResponseInputFile` - The x-coordinate to move to. + Text, image, or file output of the function call. - - `y: number` + - `ResponseInputText object { text, type }` - The y-coordinate to move to. + A text input to the model. - - `keys: optional array of string` + - `ResponseInputImage object { detail, type, file_id, image_url }` - The keys being held while moving the mouse. + An image input to the model. Learn about [image inputs](/docs/guides/vision). - - `Screenshot object { type }` + - `ResponseInputFile object { type, detail, file_data, 3 more }` - A screenshot action. + A file input to the model. - - `type: "screenshot"` + - `status: "in_progress" or "completed" or "incomplete"` - Specifies the event type. For a screenshot action, this property is always set to `screenshot`. + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `"screenshot"` + - `"in_progress"` - - `Scroll object { scroll_x, scroll_y, type, 3 more }` + - `"completed"` - A scroll action. + - `"incomplete"` - - `scroll_x: number` + - `type: "function_call_output"` - The horizontal scroll distance. + The type of the function tool call output. Always `function_call_output`. - - `scroll_y: number` + - `"function_call_output"` - The vertical scroll distance. + - `created_by: optional string` - - `type: "scroll"` + The identifier of the actor that created the item. - Specifies the event type. For a scroll action, this property is always set to `scroll`. + - `FileSearchCall object { id, queries, status, 2 more }` - - `"scroll"` + The results of a file search tool call. See the + [file search guide](/docs/guides/tools-file-search) for more information. - - `x: number` + - `id: string` - The x-coordinate where the scroll occurred. + The unique ID of the file search tool call. - - `y: number` + - `queries: array of string` - The y-coordinate where the scroll occurred. + The queries used to search for files. - - `keys: optional array of string` + - `status: "in_progress" or "searching" or "completed" or 2 more` - The keys being held while scrolling. + The status of the file search tool call. One of `in_progress`, + `searching`, `incomplete` or `failed`, - - `Type object { text, type }` + - `"in_progress"` - An action to type in text. + - `"searching"` - - `text: string` + - `"completed"` - The text to type. + - `"incomplete"` - - `type: "type"` + - `"failed"` - Specifies the event type. For a type action, this property is always set to `type`. + - `type: "file_search_call"` - - `"type"` + The type of the file search tool call. Always `file_search_call`. - - `Wait object { type }` + - `"file_search_call"` - A wait action. + - `results: optional array of object { attributes, file_id, filename, 2 more }` - - `type: "wait"` + The results of the file search tool call. - Specifies the event type. For a wait action, this property is always set to `wait`. + - `attributes: optional map[string or number or boolean]` - - `"wait"` + Set of 16 key-value pairs that can be attached to an object. This can be + useful for storing additional information about the object in a structured + format, and querying for objects via API or the dashboard. Keys are strings + with a maximum length of 64 characters. Values are strings with a maximum + length of 512 characters, booleans, or numbers. - - `actions: optional ComputerActionList` + - `string` - Flattened batched actions for `computer_use`. Each action includes an - `type` discriminator and action-specific fields. + - `number` - - `Click object { button, type, x, 2 more }` + - `boolean` - A click action. + - `file_id: optional string` - - `DoubleClick object { keys, type, x, y }` + The unique ID of the file. - A double click action. + - `filename: optional string` - - `Drag object { path, type, keys }` + The name of the file. - A drag action. + - `score: optional number` - - `Keypress object { keys, type }` + The relevance score of the file - a value between 0 and 1. - A collection of keypresses the model would like to perform. + - `text: optional string` - - `Move object { type, x, y, keys }` + The text that was retrieved from the file. - A mouse move action. + - `WebSearchCall object { id, action, status, type }` - - `Screenshot object { type }` + The results of a web search tool call. See the + [web search guide](/docs/guides/tools-web-search) for more information. - A screenshot action. + - `id: string` - - `Scroll object { scroll_x, scroll_y, type, 3 more }` + The unique ID of the web search tool call. - A scroll action. + - `action: object { type, queries, query, sources } or object { type, url } or object { pattern, type, url }` - - `Type object { text, type }` + An object describing the specific action taken in this web search call. + Includes details on how the model used the web (search, open_page, find_in_page). - An action to type in text. + - `Search object { type, queries, query, sources }` - - `Wait object { type }` + Action type "search" - Performs a web search query. - A wait action. + - `type: "search"` - - `ComputerCallOutput object { id, call_id, output, 4 more }` + The action type. - - `id: string` + - `"search"` - The unique ID of the computer call tool output. + - `queries: optional array of string` - - `call_id: string` + The search queries. - The ID of the computer tool call that produced the output. + - `query: optional string` - - `output: ResponseComputerToolCallOutputScreenshot` + The search query. - A computer screenshot image used with the computer use tool. + - `sources: optional array of object { type, url }` - - `type: "computer_screenshot"` + The sources used in the search. - Specifies the event type. For a computer screenshot, this property is - always set to `computer_screenshot`. + - `type: "url"` - - `"computer_screenshot"` + The type of source. Always `url`. - - `file_id: optional string` + - `"url"` - The identifier of an uploaded file that contains the screenshot. + - `url: string` - - `image_url: optional string` + The URL of the source. - The URL of the screenshot image. + - `OpenPage object { type, url }` - - `status: "completed" or "incomplete" or "failed" or "in_progress"` + Action type "open_page" - Opens a specific URL from search results. - The status of the message input. One of `in_progress`, `completed`, or - `incomplete`. Populated when input items are returned via API. + - `type: "open_page"` - - `"completed"` + The action type. - - `"incomplete"` + - `"open_page"` - - `"failed"` + - `url: optional string` - - `"in_progress"` + The URL opened by the model. - - `type: "computer_call_output"` + - `FindInPage object { pattern, type, url }` - The type of the computer tool call output. Always `computer_call_output`. + Action type "find_in_page": Searches for a pattern within a loaded page. - - `"computer_call_output"` + - `pattern: string` - - `acknowledged_safety_checks: optional array of object { id, code, message }` + The pattern or text to search for within the page. - The safety checks reported by the API that have been acknowledged by the - developer. + - `type: "find_in_page"` - - `id: string` + The action type. - The ID of the pending safety check. + - `"find_in_page"` - - `code: optional string` + - `url: string` - The type of the pending safety check. + The URL of the page searched for the pattern. - - `message: optional string` + - `status: "in_progress" or "searching" or "completed" or "failed"` - Details about the pending safety check. + The status of the web search tool call. - - `created_by: optional string` + - `"in_progress"` - The identifier of the actor that created the item. + - `"searching"` - - `ToolSearchCall object { id, arguments, call_id, 4 more }` + - `"completed"` - - `id: string` + - `"failed"` - The unique ID of the tool search call item. + - `type: "web_search_call"` - - `arguments: unknown` + The type of the web search tool call. Always `web_search_call`. - Arguments used for the tool search call. + - `"web_search_call"` - - `call_id: string` + - `ImageGenerationCall object { id, result, status, type }` - The unique ID of the tool search call generated by the model. + An image generation request made by the model. - - `execution: "server" or "client"` + - `id: string` - Whether tool search was executed by the server or by the client. + The unique ID of the image generation call. - - `"server"` + - `result: string` - - `"client"` + The generated image encoded in base64. - - `status: "in_progress" or "completed" or "incomplete"` + - `status: "in_progress" or "completed" or "generating" or "failed"` - The status of the tool search call item that was recorded. + The status of the image generation call. - `"in_progress"` - `"completed"` - - `"incomplete"` + - `"generating"` - - `type: "tool_search_call"` + - `"failed"` - The type of the item. Always `tool_search_call`. + - `type: "image_generation_call"` - - `"tool_search_call"` + The type of the image generation call. Always `image_generation_call`. - - `created_by: optional string` + - `"image_generation_call"` - The identifier of the actor that created the item. + - `ComputerCall object { id, call_id, pending_safety_checks, 4 more }` - - `ToolSearchOutput object { id, call_id, execution, 4 more }` + A tool call to a computer use tool. See the + [computer use guide](/docs/guides/tools-computer-use) for more information. - `id: string` - The unique ID of the tool search output item. + The unique ID of the computer call. - `call_id: string` - The unique ID of the tool search call generated by the model. - - - `execution: "server" or "client"` + An identifier used when responding to the tool call with output. - Whether tool search was executed by the server or by the client. + - `pending_safety_checks: array of object { id, code, message }` - - `"server"` + The pending safety checks for the computer call. - - `"client"` + - `id: string` - - `status: "in_progress" or "completed" or "incomplete"` + The ID of the pending safety check. - The status of the tool search output item that was recorded. + - `code: optional string` - - `"in_progress"` + The type of the pending safety check. - - `"completed"` + - `message: optional string` - - `"incomplete"` + Details about the pending safety check. - - `tools: array of object { name, parameters, strict, 3 more } or object { type, vector_store_ids, filters, 2 more } or object { type } or 12 more` + - `status: "in_progress" or "completed" or "incomplete"` - The loaded tool definitions returned by tool search. + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `Function object { name, parameters, strict, 3 more }` + - `"in_progress"` - 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). + - `"completed"` - - `name: string` + - `"incomplete"` - The name of the function to call. + - `type: "computer_call"` - - `parameters: map[unknown]` + The type of the computer call. Always `computer_call`. - A JSON schema object describing the parameters of the function. + - `"computer_call"` - - `strict: boolean` + - `action: optional ComputerAction` - Whether to enforce strict parameter validation. Default `true`. + A click action. - - `type: "function"` + - `Click object { button, type, x, 2 more }` - The type of the function tool. Always `function`. + A click action. - - `"function"` + - `button: "left" or "right" or "wheel" or 2 more` - - `defer_loading: optional boolean` + Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. - Whether this function is deferred and loaded via tool search. + - `"left"` - - `description: optional string` + - `"right"` - A description of the function. Used by the model to determine whether or not to call the function. + - `"wheel"` - - `FileSearch object { type, vector_store_ids, filters, 2 more }` + - `"back"` - 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). + - `"forward"` - - `type: "file_search"` + - `type: "click"` - The type of the file search tool. Always `file_search`. + Specifies the event type. For a click action, this property is always `click`. - - `"file_search"` + - `"click"` - - `vector_store_ids: array of string` + - `x: number` - The IDs of the vector stores to search. + The x-coordinate where the click occurred. - - `filters: optional ComparisonFilter or CompoundFilter` + - `y: number` - A filter to apply. + The y-coordinate where the click occurred. - - `ComparisonFilter object { key, type, value }` + - `keys: optional array of string` - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + The keys being held while clicking. - - `key: string` + - `DoubleClick object { keys, type, x, y }` - The key to compare against the value. + A double click action. - - `type: "eq" or "ne" or "gt" or 5 more` + - `keys: array of string` - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + The keys being held while double-clicking. - - `eq`: equals - - `ne`: not equal - - `gt`: greater than - - `gte`: greater than or equal - - `lt`: less than - - `lte`: less than or equal - - `in`: in - - `nin`: not in + - `type: "double_click"` - - `"eq"` + Specifies the event type. For a double click action, this property is always set to `double_click`. - - `"ne"` + - `"double_click"` - - `"gt"` + - `x: number` - - `"gte"` + The x-coordinate where the double click occurred. - - `"lt"` + - `y: number` - - `"lte"` + The y-coordinate where the double click occurred. - - `"in"` + - `Drag object { path, type, keys }` - - `"nin"` + A drag action. - - `value: string or number or boolean or array of string or number` + - `path: array of object { x, y }` - The value to compare against the attribute key; supports string, number, or boolean types. + An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg - - `string` + ``` + [ + { x: 100, y: 200 }, + { x: 200, y: 300 } + ] + ``` - - `number` + - `x: number` - - `boolean` + The x-coordinate. - - `array of string or number` + - `y: number` - - `string` + The y-coordinate. - - `number` + - `type: "drag"` - - `CompoundFilter object { filters, type }` + Specifies the event type. For a drag action, this property is always set to `drag`. - Combine multiple filters using `and` or `or`. + - `"drag"` - - `filters: array of ComparisonFilter or unknown` + - `keys: optional array of string` - Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. + The keys being held while dragging the mouse. - - `ComparisonFilter object { key, type, value }` + - `Keypress object { keys, type }` - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + A collection of keypresses the model would like to perform. - - `unknown` + - `keys: array of string` - - `type: "and" or "or"` + The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. - Type of operation: `and` or `or`. + - `type: "keypress"` - - `"and"` + Specifies the event type. For a keypress action, this property is always set to `keypress`. - - `"or"` + - `"keypress"` - - `max_num_results: optional number` + - `Move object { type, x, y, keys }` - The maximum number of results to return. This number should be between 1 and 50 inclusive. + A mouse move action. - - `ranking_options: optional object { hybrid_search, ranker, score_threshold }` + - `type: "move"` - Ranking options for search. + Specifies the event type. For a move action, this property is always set to `move`. - - `hybrid_search: optional object { embedding_weight, text_weight }` + - `"move"` - Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. + - `x: number` - - `embedding_weight: number` + The x-coordinate to move to. - The weight of the embedding in the reciprocal ranking fusion. + - `y: number` - - `text_weight: number` + The y-coordinate to move to. - The weight of the text in the reciprocal ranking fusion. + - `keys: optional array of string` - - `ranker: optional "auto" or "default-2024-11-15"` + The keys being held while moving the mouse. - The ranker to use for the file search. + - `Screenshot object { type }` - - `"auto"` + A screenshot action. - - `"default-2024-11-15"` + - `type: "screenshot"` - - `score_threshold: optional number` + Specifies the event type. For a screenshot action, this property is always set to `screenshot`. - The score threshold for the file search, a number between 0 and 1. Numbers closer to 1 will attempt to return only the most relevant results, but may return fewer results. + - `"screenshot"` - - `Computer object { type }` + - `Scroll object { scroll_x, scroll_y, type, 3 more }` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + A scroll action. - - `type: "computer"` + - `scroll_x: number` - The type of the computer tool. Always `computer`. + The horizontal scroll distance. - - `"computer"` + - `scroll_y: number` - - `ComputerUsePreview object { display_height, display_width, environment, type }` + The vertical scroll distance. - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `type: "scroll"` - - `display_height: number` + Specifies the event type. For a scroll action, this property is always set to `scroll`. - The height of the computer display. + - `"scroll"` - - `display_width: number` + - `x: number` - The width of the computer display. + The x-coordinate where the scroll occurred. - - `environment: "windows" or "mac" or "linux" or 2 more` + - `y: number` - The type of computer environment to control. + The y-coordinate where the scroll occurred. - - `"windows"` + - `keys: optional array of string` - - `"mac"` + The keys being held while scrolling. - - `"linux"` + - `Type object { text, type }` - - `"ubuntu"` + An action to type in text. - - `"browser"` + - `text: string` - - `type: "computer_use_preview"` + The text to type. - The type of the computer use tool. Always `computer_use_preview`. + - `type: "type"` - - `"computer_use_preview"` + Specifies the event type. For a type action, this property is always set to `type`. - - `WebSearch object { type, filters, search_context_size, user_location }` + - `"type"` - Search the Internet for sources related to the prompt. Learn more about the - [web search tool](/docs/guides/tools-web-search). + - `Wait object { type }` - - `type: "web_search" or "web_search_2025_08_26"` + A wait action. - The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. + - `type: "wait"` - - `"web_search"` + Specifies the event type. For a wait action, this property is always set to `wait`. - - `"web_search_2025_08_26"` + - `"wait"` - - `filters: optional object { allowed_domains }` + - `actions: optional ComputerActionList` - Filters for the search. + Flattened batched actions for `computer_use`. Each action includes an + `type` discriminator and action-specific fields. - - `allowed_domains: optional array of string` + - `Click object { button, type, x, 2 more }` - Allowed domains for the search. If not provided, all domains are allowed. - Subdomains of the provided domains are allowed as well. + A click action. - Example: `["pubmed.ncbi.nlm.nih.gov"]` + - `DoubleClick object { keys, type, x, y }` - - `search_context_size: optional "low" or "medium" or "high"` + A double click action. - High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. + - `Drag object { path, type, keys }` - - `"low"` + A drag action. - - `"medium"` + - `Keypress object { keys, type }` - - `"high"` + A collection of keypresses the model would like to perform. - - `user_location: optional object { city, country, region, 2 more }` + - `Move object { type, x, y, keys }` - The approximate location of the user. + A mouse move action. - - `city: optional string` + - `Screenshot object { type }` - Free text input for the city of the user, e.g. `San Francisco`. + A screenshot action. - - `country: optional string` + - `Scroll object { scroll_x, scroll_y, type, 3 more }` - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + A scroll action. - - `region: optional string` + - `Type object { text, type }` - Free text input for the region of the user, e.g. `California`. + An action to type in text. - - `timezone: optional string` + - `Wait object { type }` - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + A wait action. - - `type: optional "approximate"` + - `ComputerCallOutput object { id, call_id, output, 4 more }` - The type of location approximation. Always `approximate`. + - `id: string` - - `"approximate"` + The unique ID of the computer call tool output. - - `Mcp object { server_label, type, allowed_tools, 7 more }` + - `call_id: string` - Give the model access to additional tools via remote Model Context Protocol - (MCP) servers. [Learn more about MCP](/docs/guides/tools-remote-mcp). + The ID of the computer tool call that produced the output. - - `server_label: string` + - `output: ResponseComputerToolCallOutputScreenshot` - A label for this MCP server, used to identify it in tool calls. + A computer screenshot image used with the computer use tool. - - `type: "mcp"` + - `type: "computer_screenshot"` - The type of the MCP tool. Always `mcp`. + Specifies the event type. For a computer screenshot, this property is + always set to `computer_screenshot`. - - `"mcp"` + - `"computer_screenshot"` - - `allowed_tools: optional array of string or object { read_only, tool_names }` + - `file_id: optional string` - List of allowed tool names or a filter object. + The identifier of an uploaded file that contains the screenshot. - - `McpAllowedTools = array of string` + - `image_url: optional string` - A string array of allowed tool names + The URL of the screenshot image. - - `McpToolFilter object { read_only, tool_names }` + - `status: "completed" or "incomplete" or "failed" or "in_progress"` - A filter object to specify which tools are allowed. + The status of the message input. One of `in_progress`, `completed`, or + `incomplete`. Populated when input items are returned via API. - - `read_only: optional boolean` + - `"completed"` - Indicates whether or not a tool modifies data or is read-only. If an - MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), - it will match this filter. + - `"incomplete"` - - `tool_names: optional array of string` + - `"failed"` - List of allowed tool names. + - `"in_progress"` - - `authorization: optional string` + - `type: "computer_call_output"` - An OAuth access token that can be used with a remote MCP server, either - with a custom MCP server URL or a service connector. Your application - must handle the OAuth authorization flow and provide the token here. + The type of the computer tool call output. Always `computer_call_output`. - - `connector_id: optional "connector_dropbox" or "connector_gmail" or "connector_googlecalendar" or 5 more` + - `"computer_call_output"` - Identifier for service connectors, like those available in ChatGPT. One of - `server_url` or `connector_id` must be provided. Learn more about service - connectors [here](/docs/guides/tools-remote-mcp#connectors). + - `acknowledged_safety_checks: optional array of object { id, code, message }` - Currently supported `connector_id` values are: + The safety checks reported by the API that have been acknowledged by the + developer. - - Dropbox: `connector_dropbox` - - Gmail: `connector_gmail` - - Google Calendar: `connector_googlecalendar` - - Google Drive: `connector_googledrive` - - Microsoft Teams: `connector_microsoftteams` - - Outlook Calendar: `connector_outlookcalendar` - - Outlook Email: `connector_outlookemail` - - SharePoint: `connector_sharepoint` + - `id: string` - - `"connector_dropbox"` + The ID of the pending safety check. - - `"connector_gmail"` + - `code: optional string` - - `"connector_googlecalendar"` + The type of the pending safety check. - - `"connector_googledrive"` + - `message: optional string` - - `"connector_microsoftteams"` + Details about the pending safety check. - - `"connector_outlookcalendar"` + - `created_by: optional string` - - `"connector_outlookemail"` + The identifier of the actor that created the item. - - `"connector_sharepoint"` + - `ToolSearchCall object { id, arguments, call_id, 4 more }` - - `defer_loading: optional boolean` + - `id: string` - Whether this MCP tool is deferred and discovered via tool search. + The unique ID of the tool search call item. - - `headers: optional map[string]` + - `arguments: unknown` - Optional HTTP headers to send to the MCP server. Use for authentication - or other purposes. + Arguments used for the tool search call. - - `require_approval: optional object { always, never } or "always" or "never"` + - `call_id: string` - Specify which of the MCP server's tools require approval. + The unique ID of the tool search call generated by the model. - - `McpToolApprovalFilter object { always, never }` + - `execution: "server" or "client"` - Specify which of the MCP server's tools require approval. Can be - `always`, `never`, or a filter object associated with tools - that require approval. + Whether tool search was executed by the server or by the client. - - `always: optional object { read_only, tool_names }` + - `"server"` - A filter object to specify which tools are allowed. + - `"client"` - - `read_only: optional boolean` + - `status: "in_progress" or "completed" or "incomplete"` - Indicates whether or not a tool modifies data or is read-only. If an - MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), - it will match this filter. + The status of the tool search call item that was recorded. - - `tool_names: optional array of string` + - `"in_progress"` - List of allowed tool names. + - `"completed"` - - `never: optional object { read_only, tool_names }` + - `"incomplete"` - A filter object to specify which tools are allowed. + - `type: "tool_search_call"` - - `read_only: optional boolean` + The type of the item. Always `tool_search_call`. - Indicates whether or not a tool modifies data or is read-only. If an - MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), - it will match this filter. + - `"tool_search_call"` - - `tool_names: optional array of string` + - `created_by: optional string` - List of allowed tool names. + The identifier of the actor that created the item. - - `McpToolApprovalSetting = "always" or "never"` + - `ToolSearchOutput object { id, call_id, execution, 4 more }` - Specify a single approval policy for all tools. One of `always` or - `never`. When set to `always`, all tools will require approval. When - set to `never`, all tools will not require approval. + - `id: string` - - `"always"` + The unique ID of the tool search output item. - - `"never"` + - `call_id: string` - - `server_description: optional string` + The unique ID of the tool search call generated by the model. - Optional description of the MCP server, used to provide more context. + - `execution: "server" or "client"` - - `server_url: optional string` + Whether tool search was executed by the server or by the client. - The URL for the MCP server. One of `server_url` or `connector_id` must be - provided. + - `"server"` - - `CodeInterpreter object { container, type }` + - `"client"` - A tool that runs Python code to help generate a response to a prompt. + - `status: "in_progress" or "completed" or "incomplete"` - - `container: string or object { type, file_ids, memory_limit, network_policy }` + The status of the tool search output item that was recorded. - The code interpreter container. Can be a container ID or an object that - specifies uploaded file IDs to make available to your code, along with an - optional `memory_limit` setting. + - `"in_progress"` - - `string` + - `"completed"` - The container ID. + - `"incomplete"` - - `CodeInterpreterToolAuto object { type, file_ids, memory_limit, network_policy }` + - `tools: array of object { name, parameters, strict, 3 more } or object { type, vector_store_ids, filters, 2 more } or object { type } or 12 more` - Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. + The loaded tool definitions returned by tool search. - - `type: "auto"` + - `Function object { name, parameters, strict, 3 more }` - Always `auto`. + Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). - - `"auto"` + - `name: string` - - `file_ids: optional array of string` + The name of the function to call. - An optional list of uploaded files to make available to your code. + - `parameters: map[unknown]` - - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` + A JSON schema object describing the parameters of the function. - The memory limit for the code interpreter container. + - `strict: boolean` - - `"1g"` + Whether to enforce strict parameter validation. Default `true`. - - `"4g"` + - `type: "function"` - - `"16g"` + The type of the function tool. Always `function`. - - `"64g"` + - `"function"` - - `network_policy: optional ContainerNetworkPolicyDisabled or ContainerNetworkPolicyAllowlist` + - `defer_loading: optional boolean` - Network access policy for the container. + Whether this function is deferred and loaded via tool search. - - `ContainerNetworkPolicyDisabled object { type }` + - `description: optional string` - - `type: "disabled"` + A description of the function. Used by the model to determine whether or not to call the function. - Disable outbound network access. Always `disabled`. + - `FileSearch object { type, vector_store_ids, filters, 2 more }` - - `"disabled"` + 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). - - `ContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` + - `type: "file_search"` - - `allowed_domains: array of string` + The type of the file search tool. Always `file_search`. - A list of allowed domains when type is `allowlist`. + - `"file_search"` - - `type: "allowlist"` + - `vector_store_ids: array of string` - Allow outbound network access only to specified domains. Always `allowlist`. + The IDs of the vector stores to search. - - `"allowlist"` + - `filters: optional ComparisonFilter or CompoundFilter` - - `domain_secrets: optional array of ContainerNetworkPolicyDomainSecret` + A filter to apply. - Optional domain-scoped secrets for allowlisted domains. + - `ComparisonFilter object { key, type, value }` - - `domain: string` + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - The domain associated with the secret. + - `key: string` - - `name: string` + The key to compare against the value. - The name of the secret to inject for the domain. + - `type: "eq" or "ne" or "gt" or 5 more` - - `value: string` + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - The secret value to inject for the domain. + - `eq`: equals + - `ne`: not equal + - `gt`: greater than + - `gte`: greater than or equal + - `lt`: less than + - `lte`: less than or equal + - `in`: in + - `nin`: not in - - `type: "code_interpreter"` + - `"eq"` - The type of the code interpreter tool. Always `code_interpreter`. + - `"ne"` - - `"code_interpreter"` + - `"gt"` - - `ImageGeneration object { type, action, background, 9 more }` + - `"gte"` - A tool that generates images using the GPT image models. + - `"lt"` - - `type: "image_generation"` + - `"lte"` - The type of the image generation tool. Always `image_generation`. + - `"in"` - - `"image_generation"` + - `"nin"` - - `action: optional "generate" or "edit" or "auto"` + - `value: string or number or boolean or array of string or number` - Whether to generate a new image or edit an existing image. Default: `auto`. + The value to compare against the attribute key; supports string, number, or boolean types. - - `"generate"` + - `string` - - `"edit"` + - `number` - - `"auto"` + - `boolean` - - `background: optional "transparent" or "opaque" or "auto"` + - `array of string or number` - Background type for the generated image. One of `transparent`, - `opaque`, or `auto`. Default: `auto`. + - `string` - - `"transparent"` + - `number` - - `"opaque"` + - `CompoundFilter object { filters, type }` - - `"auto"` + Combine multiple filters using `and` or `or`. - - `input_fidelity: optional "high" or "low"` + - `filters: array of ComparisonFilter or unknown` - Control how much effort the model will exert to match the style and features, especially facial features, of input images. This parameter is only supported for `gpt-image-1` and `gpt-image-1.5` and later models, unsupported for `gpt-image-1-mini`. Supports `high` and `low`. Defaults to `low`. + Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. - - `"high"` + - `ComparisonFilter object { key, type, value }` - - `"low"` + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - - `input_image_mask: optional object { file_id, image_url }` + - `unknown` - Optional mask for inpainting. Contains `image_url` - (string, optional) and `file_id` (string, optional). + - `type: "and" or "or"` - - `file_id: optional string` + Type of operation: `and` or `or`. - File ID for the mask image. + - `"and"` - - `image_url: optional string` + - `"or"` - Base64-encoded mask image. + - `max_num_results: optional number` - - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` + The maximum number of results to return. This number should be between 1 and 50 inclusive. - The image generation model to use. Default: `gpt-image-1`. + - `ranking_options: optional object { hybrid_search, ranker, score_threshold }` - - `string` + Ranking options for search. - - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` + - `hybrid_search: optional object { embedding_weight, text_weight }` - The image generation model to use. Default: `gpt-image-1`. + Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. - - `"gpt-image-1"` + - `embedding_weight: number` - - `"gpt-image-1-mini"` + The weight of the embedding in the reciprocal ranking fusion. - - `"gpt-image-1.5"` + - `text_weight: number` - - `moderation: optional "auto" or "low"` + The weight of the text in the reciprocal ranking fusion. - Moderation level for the generated image. Default: `auto`. + - `ranker: optional "auto" or "default-2024-11-15"` + + The ranker to use for the file search. - `"auto"` - - `"low"` + - `"default-2024-11-15"` - - `output_compression: optional number` + - `score_threshold: optional number` + + The score threshold for the file search, a number between 0 and 1. Numbers closer to 1 will attempt to return only the most relevant results, but may return fewer results. - Compression level for the output image. Default: 100. + - `Computer object { type }` - - `output_format: optional "png" or "webp" or "jpeg"` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - The output format of the generated image. One of `png`, `webp`, or - `jpeg`. Default: `png`. + - `type: "computer"` - - `"png"` + The type of the computer tool. Always `computer`. - - `"webp"` + - `"computer"` - - `"jpeg"` + - `ComputerUsePreview object { display_height, display_width, environment, type }` - - `partial_images: optional number` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - Number of partial images to generate in streaming mode, from 0 (default value) to 3. + - `display_height: number` - - `quality: optional "low" or "medium" or "high" or "auto"` + The height of the computer display. - The quality of the generated image. One of `low`, `medium`, `high`, - or `auto`. Default: `auto`. + - `display_width: number` - - `"low"` + The width of the computer display. - - `"medium"` + - `environment: "windows" or "mac" or "linux" or 2 more` - - `"high"` + The type of computer environment to control. - - `"auto"` + - `"windows"` - - `size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or "auto"` + - `"mac"` - The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. + - `"linux"` - - `string` + - `"ubuntu"` - - `"1024x1024" or "1024x1536" or "1536x1024" or "auto"` + - `"browser"` - The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. + - `type: "computer_use_preview"` - - `"1024x1024"` + The type of the computer use tool. Always `computer_use_preview`. - - `"1024x1536"` + - `"computer_use_preview"` - - `"1536x1024"` + - `WebSearch object { type, filters, search_context_size, user_location }` - - `"auto"` + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](/docs/guides/tools-web-search). - - `LocalShell object { type }` + - `type: "web_search" or "web_search_2025_08_26"` - A tool that allows the model to execute shell commands in a local environment. + The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. - - `type: "local_shell"` + - `"web_search"` - The type of the local shell tool. Always `local_shell`. + - `"web_search_2025_08_26"` - - `"local_shell"` + - `filters: optional object { allowed_domains }` - - `Shell object { type, environment }` + Filters for the search. - A tool that allows the model to execute shell commands. + - `allowed_domains: optional array of string` - - `type: "shell"` + Allowed domains for the search. If not provided, all domains are allowed. + Subdomains of the provided domains are allowed as well. - The type of the shell tool. Always `shell`. + Example: `["pubmed.ncbi.nlm.nih.gov"]` - - `"shell"` + - `search_context_size: optional "low" or "medium" or "high"` - - `environment: optional ContainerAuto or LocalEnvironment or ContainerReference` + High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. - - `ContainerAuto object { type, file_ids, memory_limit, 2 more }` + - `"low"` - - `type: "container_auto"` + - `"medium"` - Automatically creates a container for this request + - `"high"` - - `"container_auto"` + - `user_location: optional object { city, country, region, 2 more }` - - `file_ids: optional array of string` + The approximate location of the user. - An optional list of uploaded files to make available to your code. + - `city: optional string` - - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` + Free text input for the city of the user, e.g. `San Francisco`. - The memory limit for the container. + - `country: optional string` - - `"1g"` + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - - `"4g"` + - `region: optional string` - - `"16g"` + Free text input for the region of the user, e.g. `California`. - - `"64g"` + - `timezone: optional string` - - `network_policy: optional ContainerNetworkPolicyDisabled or ContainerNetworkPolicyAllowlist` + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - Network access policy for the container. + - `type: optional "approximate"` - - `ContainerNetworkPolicyDisabled object { type }` + The type of location approximation. Always `approximate`. - - `ContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` + - `"approximate"` - - `skills: optional array of SkillReference or InlineSkill` + - `Mcp object { server_label, type, allowed_tools, 7 more }` - An optional list of skills referenced by id or inline data. + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](/docs/guides/tools-remote-mcp). - - `SkillReference object { skill_id, type, version }` + - `server_label: string` - - `skill_id: string` + A label for this MCP server, used to identify it in tool calls. - The ID of the referenced skill. + - `type: "mcp"` - - `type: "skill_reference"` + The type of the MCP tool. Always `mcp`. - References a skill created with the /v1/skills endpoint. + - `"mcp"` - - `"skill_reference"` + - `allowed_tools: optional array of string or object { read_only, tool_names }` - - `version: optional string` + List of allowed tool names or a filter object. - Optional skill version. Use a positive integer or 'latest'. Omit for default. + - `McpAllowedTools = array of string` - - `InlineSkill object { description, name, source, type }` + A string array of allowed tool names - - `description: string` + - `McpToolFilter object { read_only, tool_names }` - The description of the skill. + A filter object to specify which tools are allowed. - - `name: string` + - `read_only: optional boolean` - The name of the skill. + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. - - `source: InlineSkillSource` + - `tool_names: optional array of string` - Inline skill payload + List of allowed tool names. - - `data: string` + - `authorization: optional string` - Base64-encoded skill zip bundle. + An OAuth access token that can be used with a remote MCP server, either + with a custom MCP server URL or a service connector. Your application + must handle the OAuth authorization flow and provide the token here. - - `media_type: "application/zip"` + - `connector_id: optional "connector_dropbox" or "connector_gmail" or "connector_googlecalendar" or 5 more` - The media type of the inline skill payload. Must be `application/zip`. + Identifier for service connectors, like those available in ChatGPT. One of + `server_url` or `connector_id` must be provided. Learn more about service + connectors [here](/docs/guides/tools-remote-mcp#connectors). - - `"application/zip"` + Currently supported `connector_id` values are: - - `type: "base64"` + - Dropbox: `connector_dropbox` + - Gmail: `connector_gmail` + - Google Calendar: `connector_googlecalendar` + - Google Drive: `connector_googledrive` + - Microsoft Teams: `connector_microsoftteams` + - Outlook Calendar: `connector_outlookcalendar` + - Outlook Email: `connector_outlookemail` + - SharePoint: `connector_sharepoint` - The type of the inline skill source. Must be `base64`. + - `"connector_dropbox"` - - `"base64"` + - `"connector_gmail"` - - `type: "inline"` + - `"connector_googlecalendar"` - Defines an inline skill for this request. + - `"connector_googledrive"` - - `"inline"` + - `"connector_microsoftteams"` - - `LocalEnvironment object { type, skills }` + - `"connector_outlookcalendar"` - - `type: "local"` + - `"connector_outlookemail"` - Use a local computer environment. + - `"connector_sharepoint"` - - `"local"` + - `defer_loading: optional boolean` - - `skills: optional array of LocalSkill` + Whether this MCP tool is deferred and discovered via tool search. - An optional list of skills. + - `headers: optional map[string]` - - `description: string` + Optional HTTP headers to send to the MCP server. Use for authentication + or other purposes. - The description of the skill. + - `require_approval: optional object { always, never } or "always" or "never"` - - `name: string` + Specify which of the MCP server's tools require approval. - The name of the skill. + - `McpToolApprovalFilter object { always, never }` - - `path: string` + Specify which of the MCP server's tools require approval. Can be + `always`, `never`, or a filter object associated with tools + that require approval. - The path to the directory containing the skill. + - `always: optional object { read_only, tool_names }` - - `ContainerReference object { container_id, type }` + A filter object to specify which tools are allowed. - - `container_id: string` + - `read_only: optional boolean` - The ID of the referenced container. + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. - - `type: "container_reference"` + - `tool_names: optional array of string` - References a container created with the /v1/containers endpoint + List of allowed tool names. - - `"container_reference"` + - `never: optional object { read_only, tool_names }` - - `Custom object { name, type, defer_loading, 2 more }` + A filter object to specify which tools are allowed. - A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) + - `read_only: optional boolean` - - `name: string` + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. - The name of the custom tool, used to identify it in tool calls. + - `tool_names: optional array of string` - - `type: "custom"` + List of allowed tool names. - The type of the custom tool. Always `custom`. + - `McpToolApprovalSetting = "always" or "never"` - - `"custom"` + Specify a single approval policy for all tools. One of `always` or + `never`. When set to `always`, all tools will require approval. When + set to `never`, all tools will not require approval. - - `defer_loading: optional boolean` + - `"always"` - Whether this tool should be deferred and discovered via tool search. + - `"never"` - - `description: optional string` + - `server_description: optional string` - Optional description of the custom tool, used to provide more context. + Optional description of the MCP server, used to provide more context. - - `format: optional CustomToolInputFormat` + - `server_url: optional string` - The input format for the custom tool. Default is unconstrained text. + The URL for the MCP server. One of `server_url` or `connector_id` must be + provided. - - `Text object { type }` + - `CodeInterpreter object { container, type }` - Unconstrained free-form text. + A tool that runs Python code to help generate a response to a prompt. - - `type: "text"` + - `container: string or object { type, file_ids, memory_limit, network_policy }` - Unconstrained text format. Always `text`. + The code interpreter container. Can be a container ID or an object that + specifies uploaded file IDs to make available to your code, along with an + optional `memory_limit` setting. - - `"text"` + - `string` - - `Grammar object { definition, syntax, type }` + The container ID. - A grammar defined by the user. + - `CodeInterpreterToolAuto object { type, file_ids, memory_limit, network_policy }` - - `definition: string` + Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. - The grammar definition. + - `type: "auto"` - - `syntax: "lark" or "regex"` + Always `auto`. - The syntax of the grammar definition. One of `lark` or `regex`. + - `"auto"` - - `"lark"` + - `file_ids: optional array of string` - - `"regex"` + An optional list of uploaded files to make available to your code. - - `type: "grammar"` + - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` - Grammar format. Always `grammar`. + The memory limit for the code interpreter container. - - `"grammar"` + - `"1g"` - - `Namespace object { description, name, tools, type }` + - `"4g"` - Groups function/custom tools under a shared namespace. + - `"16g"` - - `description: string` + - `"64g"` - A description of the namespace shown to the model. + - `network_policy: optional ContainerNetworkPolicyDisabled or ContainerNetworkPolicyAllowlist` - - `name: string` + Network access policy for the container. - The namespace name used in tool calls (for example, `crm`). + - `ContainerNetworkPolicyDisabled object { type }` - - `tools: array of object { name, type, defer_loading, 3 more } or object { name, type, defer_loading, 2 more }` + - `type: "disabled"` - The function/custom tools available inside this namespace. + Disable outbound network access. Always `disabled`. - - `Function object { name, type, defer_loading, 3 more }` + - `"disabled"` - - `name: string` + - `ContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` - - `type: "function"` + - `allowed_domains: array of string` - - `"function"` + A list of allowed domains when type is `allowlist`. - - `defer_loading: optional boolean` + - `type: "allowlist"` - Whether this function should be deferred and discovered via tool search. + Allow outbound network access only to specified domains. Always `allowlist`. - - `description: optional string` + - `"allowlist"` - - `parameters: optional unknown` + - `domain_secrets: optional array of ContainerNetworkPolicyDomainSecret` - - `strict: optional boolean` + Optional domain-scoped secrets for allowlisted domains. - - `Custom object { name, type, defer_loading, 2 more }` + - `domain: string` - A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) + The domain associated with the secret. - `name: string` - The name of the custom tool, used to identify it in tool calls. - - - `type: "custom"` - - The type of the custom tool. Always `custom`. + The name of the secret to inject for the domain. - - `"custom"` + - `value: string` - - `defer_loading: optional boolean` + The secret value to inject for the domain. - Whether this tool should be deferred and discovered via tool search. + - `type: "code_interpreter"` - - `description: optional string` + The type of the code interpreter tool. Always `code_interpreter`. - Optional description of the custom tool, used to provide more context. + - `"code_interpreter"` - - `format: optional CustomToolInputFormat` + - `ImageGeneration object { type, action, background, 9 more }` - The input format for the custom tool. Default is unconstrained text. + A tool that generates images using the GPT image models. - - `type: "namespace"` + - `type: "image_generation"` - The type of the tool. Always `namespace`. + The type of the image generation tool. Always `image_generation`. - - `"namespace"` + - `"image_generation"` - - `ToolSearch object { type, description, execution, parameters }` + - `action: optional "generate" or "edit" or "auto"` - Hosted or BYOT tool search configuration for deferred tools. + Whether to generate a new image or edit an existing image. Default: `auto`. - - `type: "tool_search"` + - `"generate"` - The type of the tool. Always `tool_search`. + - `"edit"` - - `"tool_search"` + - `"auto"` - - `description: optional string` + - `background: optional "transparent" or "opaque" or "auto"` - Description shown to the model for a client-executed tool search tool. + Background type for the generated image. One of `transparent`, + `opaque`, or `auto`. Default: `auto`. - - `execution: optional "server" or "client"` + - `"transparent"` - Whether tool search is executed by the server or by the client. + - `"opaque"` - - `"server"` + - `"auto"` - - `"client"` + - `input_fidelity: optional "high" or "low"` - - `parameters: optional unknown` + Control how much effort the model will exert to match the style and features, especially facial features, of input images. This parameter is only supported for `gpt-image-1` and `gpt-image-1.5` and later models, unsupported for `gpt-image-1-mini`. Supports `high` and `low`. Defaults to `low`. - Parameter schema for a client-executed tool search tool. + - `"high"` - - `WebSearchPreview object { type, search_content_types, search_context_size, user_location }` + - `"low"` - This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + - `input_image_mask: optional object { file_id, image_url }` - - `type: "web_search_preview" or "web_search_preview_2025_03_11"` + Optional mask for inpainting. Contains `image_url` + (string, optional) and `file_id` (string, optional). - The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. + - `file_id: optional string` - - `"web_search_preview"` + File ID for the mask image. - - `"web_search_preview_2025_03_11"` + - `image_url: optional string` - - `search_content_types: optional array of "text" or "image"` + Base64-encoded mask image. - - `"text"` + - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` - - `"image"` + The image generation model to use. Default: `gpt-image-1`. - - `search_context_size: optional "low" or "medium" or "high"` + - `string` - High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. + - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` - - `"low"` + The image generation model to use. Default: `gpt-image-1`. - - `"medium"` + - `"gpt-image-1"` - - `"high"` + - `"gpt-image-1-mini"` - - `user_location: optional object { type, city, country, 2 more }` + - `"gpt-image-1.5"` - The user's location. + - `moderation: optional "auto" or "low"` - - `type: "approximate"` + Moderation level for the generated image. Default: `auto`. - The type of location approximation. Always `approximate`. + - `"auto"` - - `"approximate"` + - `"low"` - - `city: optional string` + - `output_compression: optional number` - Free text input for the city of the user, e.g. `San Francisco`. + Compression level for the output image. Default: 100. - - `country: optional string` + - `output_format: optional "png" or "webp" or "jpeg"` - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + The output format of the generated image. One of `png`, `webp`, or + `jpeg`. Default: `png`. - - `region: optional string` + - `"png"` - Free text input for the region of the user, e.g. `California`. + - `"webp"` - - `timezone: optional string` + - `"jpeg"` - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + - `partial_images: optional number` - - `ApplyPatch object { type }` + Number of partial images to generate in streaming mode, from 0 (default value) to 3. - Allows the assistant to create, delete, or update files using unified diffs. + - `quality: optional "low" or "medium" or "high" or "auto"` - - `type: "apply_patch"` + The quality of the generated image. One of `low`, `medium`, `high`, + or `auto`. Default: `auto`. - The type of the tool. Always `apply_patch`. + - `"low"` - - `"apply_patch"` + - `"medium"` - - `type: "tool_search_output"` + - `"high"` - The type of the item. Always `tool_search_output`. + - `"auto"` - - `"tool_search_output"` + - `size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or "auto"` - - `created_by: optional string` + The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. - The identifier of the actor that created the item. + - `string` - - `Reasoning object { id, summary, type, 3 more }` + - `"1024x1024" or "1024x1536" or "1536x1024" or "auto"` - A description of the chain of thought used by a reasoning model while generating - a response. Be sure to include these items in your `input` to the Responses API - for subsequent turns of a conversation if you are manually - [managing context](/docs/guides/conversation-state). + The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. - - `id: string` + - `"1024x1024"` - The unique identifier of the reasoning content. + - `"1024x1536"` - - `summary: array of SummaryTextContent` + - `"1536x1024"` - Reasoning summary content. + - `"auto"` - - `text: string` + - `LocalShell object { type }` - A summary of the reasoning output from the model so far. + A tool that allows the model to execute shell commands in a local environment. - - `type: "summary_text"` + - `type: "local_shell"` - The type of the object. Always `summary_text`. + The type of the local shell tool. Always `local_shell`. - - `type: "reasoning"` + - `"local_shell"` - The type of the object. Always `reasoning`. + - `Shell object { type, environment }` - - `"reasoning"` + A tool that allows the model to execute shell commands. - - `content: optional array of object { text, type }` + - `type: "shell"` - Reasoning text content. + The type of the shell tool. Always `shell`. - - `text: string` + - `"shell"` - The reasoning text from the model. + - `environment: optional ContainerAuto or LocalEnvironment or ContainerReference` - - `type: "reasoning_text"` + - `ContainerAuto object { type, file_ids, memory_limit, 2 more }` - The type of the reasoning text. Always `reasoning_text`. + - `type: "container_auto"` - - `"reasoning_text"` + Automatically creates a container for this request - - `encrypted_content: optional string` + - `"container_auto"` - The encrypted content of the reasoning item - populated when a response is - generated with `reasoning.encrypted_content` in the `include` parameter. + - `file_ids: optional array of string` - - `status: optional "in_progress" or "completed" or "incomplete"` + An optional list of uploaded files to make available to your code. - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` - - `"in_progress"` + The memory limit for the container. - - `"completed"` + - `"1g"` - - `"incomplete"` + - `"4g"` - - `Compaction object { id, encrypted_content, type, created_by }` + - `"16g"` - A compaction item generated by the [`v1/responses/compact` API](/docs/api-reference/responses/compact). + - `"64g"` - - `id: string` + - `network_policy: optional ContainerNetworkPolicyDisabled or ContainerNetworkPolicyAllowlist` - The unique ID of the compaction item. + Network access policy for the container. - - `encrypted_content: string` + - `ContainerNetworkPolicyDisabled object { type }` - The encrypted content that was produced by compaction. + - `ContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` - - `type: "compaction"` + - `skills: optional array of SkillReference or InlineSkill` - The type of the item. Always `compaction`. + An optional list of skills referenced by id or inline data. - - `"compaction"` + - `SkillReference object { skill_id, type, version }` - - `created_by: optional string` + - `skill_id: string` - The identifier of the actor that created the item. + The ID of the referenced skill. - - `CodeInterpreterCall object { id, code, container_id, 3 more }` + - `type: "skill_reference"` - A tool call to run code. + References a skill created with the /v1/skills endpoint. - - `id: string` + - `"skill_reference"` - The unique ID of the code interpreter tool call. + - `version: optional string` - - `code: string` + Optional skill version. Use a positive integer or 'latest'. Omit for default. - The code to run, or null if not available. + - `InlineSkill object { description, name, source, type }` - - `container_id: string` + - `description: string` - The ID of the container used to run the code. + The description of the skill. - - `outputs: array of object { logs, type } or object { type, url }` + - `name: string` - The outputs generated by the code interpreter, such as logs or images. - Can be null if no outputs are available. + The name of the skill. - - `Logs object { logs, type }` + - `source: InlineSkillSource` - The logs output from the code interpreter. + Inline skill payload - - `logs: string` + - `data: string` - The logs output from the code interpreter. + Base64-encoded skill zip bundle. - - `type: "logs"` + - `media_type: "application/zip"` - The type of the output. Always `logs`. + The media type of the inline skill payload. Must be `application/zip`. - - `"logs"` + - `"application/zip"` - - `Image object { type, url }` + - `type: "base64"` - The image output from the code interpreter. + The type of the inline skill source. Must be `base64`. - - `type: "image"` + - `"base64"` - The type of the output. Always `image`. + - `type: "inline"` - - `"image"` + Defines an inline skill for this request. - - `url: string` + - `"inline"` - The URL of the image output from the code interpreter. + - `LocalEnvironment object { type, skills }` - - `status: "in_progress" or "completed" or "incomplete" or 2 more` + - `type: "local"` - The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. + Use a local computer environment. - - `"in_progress"` + - `"local"` - - `"completed"` + - `skills: optional array of LocalSkill` - - `"incomplete"` + An optional list of skills. - - `"interpreting"` + - `description: string` - - `"failed"` + The description of the skill. - - `type: "code_interpreter_call"` + - `name: string` - The type of the code interpreter tool call. Always `code_interpreter_call`. + The name of the skill. - - `"code_interpreter_call"` + - `path: string` - - `LocalShellCall object { id, action, call_id, 2 more }` + The path to the directory containing the skill. - A tool call to run a command on the local shell. + - `ContainerReference object { container_id, type }` - - `id: string` + - `container_id: string` - The unique ID of the local shell call. + The ID of the referenced container. - - `action: object { command, env, type, 3 more }` + - `type: "container_reference"` - Execute a shell command on the server. + References a container created with the /v1/containers endpoint - - `command: array of string` + - `"container_reference"` - The command to run. + - `Custom object { name, type, defer_loading, 2 more }` - - `env: map[string]` + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) - Environment variables to set for the command. + - `name: string` - - `type: "exec"` + The name of the custom tool, used to identify it in tool calls. - The type of the local shell action. Always `exec`. + - `type: "custom"` - - `"exec"` + The type of the custom tool. Always `custom`. - - `timeout_ms: optional number` + - `"custom"` - Optional timeout in milliseconds for the command. + - `defer_loading: optional boolean` - - `user: optional string` + Whether this tool should be deferred and discovered via tool search. - Optional user to run the command as. + - `description: optional string` - - `working_directory: optional string` + Optional description of the custom tool, used to provide more context. - Optional working directory to run the command in. + - `format: optional CustomToolInputFormat` - - `call_id: string` + The input format for the custom tool. Default is unconstrained text. - The unique ID of the local shell tool call generated by the model. + - `Text object { type }` - - `status: "in_progress" or "completed" or "incomplete"` + Unconstrained free-form text. - The status of the local shell call. + - `type: "text"` - - `"in_progress"` + Unconstrained text format. Always `text`. - - `"completed"` + - `"text"` - - `"incomplete"` + - `Grammar object { definition, syntax, type }` - - `type: "local_shell_call"` + A grammar defined by the user. - The type of the local shell call. Always `local_shell_call`. + - `definition: string` - - `"local_shell_call"` + The grammar definition. - - `LocalShellCallOutput object { id, output, type, status }` + - `syntax: "lark" or "regex"` - The output of a local shell tool call. + The syntax of the grammar definition. One of `lark` or `regex`. - - `id: string` + - `"lark"` - The unique ID of the local shell tool call generated by the model. + - `"regex"` - - `output: string` + - `type: "grammar"` - A JSON string of the output of the local shell tool call. + Grammar format. Always `grammar`. - - `type: "local_shell_call_output"` + - `"grammar"` - The type of the local shell tool call output. Always `local_shell_call_output`. + - `Namespace object { description, name, tools, type }` - - `"local_shell_call_output"` + Groups function/custom tools under a shared namespace. - - `status: optional "in_progress" or "completed" or "incomplete"` + - `description: string` - The status of the item. One of `in_progress`, `completed`, or `incomplete`. + A description of the namespace shown to the model. - - `"in_progress"` + - `name: string` - - `"completed"` + The namespace name used in tool calls (for example, `crm`). - - `"incomplete"` + - `tools: array of object { name, type, defer_loading, 3 more } or object { name, type, defer_loading, 2 more }` - - `ShellCall object { id, action, call_id, 4 more }` + The function/custom tools available inside this namespace. - A tool call that executes one or more shell commands in a managed environment. + - `Function object { name, type, defer_loading, 3 more }` - - `id: string` + - `name: string` - The unique ID of the shell tool call. Populated when this item is returned via API. + - `type: "function"` - - `action: object { commands, max_output_length, timeout_ms }` + - `"function"` - The shell commands and limits that describe how to run the tool call. + - `defer_loading: optional boolean` - - `commands: array of string` + Whether this function should be deferred and discovered via tool search. - - `max_output_length: number` + - `description: optional string` - Optional maximum number of characters to return from each command. + - `parameters: optional unknown` - - `timeout_ms: number` + - `strict: optional boolean` - Optional timeout in milliseconds for the commands. + - `Custom object { name, type, defer_loading, 2 more }` - - `call_id: string` + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) - The unique ID of the shell tool call generated by the model. + - `name: string` - - `environment: ResponseLocalEnvironment or ResponseContainerReference` + The name of the custom tool, used to identify it in tool calls. - Represents the use of a local environment to perform shell actions. + - `type: "custom"` - - `ResponseLocalEnvironment object { type }` + The type of the custom tool. Always `custom`. - Represents the use of a local environment to perform shell actions. + - `"custom"` - - `type: "local"` + - `defer_loading: optional boolean` - The environment type. Always `local`. + Whether this tool should be deferred and discovered via tool search. - - `"local"` + - `description: optional string` - - `ResponseContainerReference object { container_id, type }` + Optional description of the custom tool, used to provide more context. - Represents a container created with /v1/containers. + - `format: optional CustomToolInputFormat` - - `container_id: string` + The input format for the custom tool. Default is unconstrained text. - - `type: "container_reference"` + - `type: "namespace"` - The environment type. Always `container_reference`. + The type of the tool. Always `namespace`. - - `"container_reference"` + - `"namespace"` - - `status: "in_progress" or "completed" or "incomplete"` + - `ToolSearch object { type, description, execution, parameters }` - The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. + Hosted or BYOT tool search configuration for deferred tools. - - `"in_progress"` + - `type: "tool_search"` - - `"completed"` + The type of the tool. Always `tool_search`. - - `"incomplete"` + - `"tool_search"` - - `type: "shell_call"` + - `description: optional string` - The type of the item. Always `shell_call`. + Description shown to the model for a client-executed tool search tool. - - `"shell_call"` + - `execution: optional "server" or "client"` - - `created_by: optional string` + Whether tool search is executed by the server or by the client. - The ID of the entity that created this tool call. + - `"server"` - - `ShellCallOutput object { id, call_id, max_output_length, 4 more }` + - `"client"` - The output of a shell tool call that was emitted. + - `parameters: optional unknown` - - `id: string` + Parameter schema for a client-executed tool search tool. - The unique ID of the shell call output. Populated when this item is returned via API. + - `WebSearchPreview object { type, search_content_types, search_context_size, user_location }` - - `call_id: string` + This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - The unique ID of the shell tool call generated by the model. + - `type: "web_search_preview" or "web_search_preview_2025_03_11"` - - `max_output_length: number` + The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. - The maximum length of the shell command output. This is generated by the model and should be passed back with the raw output. + - `"web_search_preview"` - - `output: array of object { outcome, stderr, stdout, created_by }` + - `"web_search_preview_2025_03_11"` - An array of shell call output contents + - `search_content_types: optional array of "text" or "image"` - - `outcome: object { type } or object { exit_code, type }` + - `"text"` - Represents either an exit outcome (with an exit code) or a timeout outcome for a shell call output chunk. + - `"image"` - - `Timeout object { type }` + - `search_context_size: optional "low" or "medium" or "high"` - Indicates that the shell call exceeded its configured time limit. + High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. - - `type: "timeout"` + - `"low"` - The outcome type. Always `timeout`. + - `"medium"` - - `"timeout"` + - `"high"` - - `Exit object { exit_code, type }` + - `user_location: optional object { type, city, country, 2 more }` - Indicates that the shell commands finished and returned an exit code. + The user's location. - - `exit_code: number` + - `type: "approximate"` - Exit code from the shell process. + The type of location approximation. Always `approximate`. - - `type: "exit"` + - `"approximate"` - The outcome type. Always `exit`. + - `city: optional string` - - `"exit"` + Free text input for the city of the user, e.g. `San Francisco`. - - `stderr: string` + - `country: optional string` - The standard error output that was captured. + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - - `stdout: string` + - `region: optional string` - The standard output that was captured. + Free text input for the region of the user, e.g. `California`. - - `created_by: optional string` + - `timezone: optional string` - The identifier of the actor that created the item. + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - - `status: "in_progress" or "completed" or "incomplete"` + - `ApplyPatch object { type }` - The status of the shell call output. One of `in_progress`, `completed`, or `incomplete`. + Allows the assistant to create, delete, or update files using unified diffs. - - `"in_progress"` + - `type: "apply_patch"` - - `"completed"` + The type of the tool. Always `apply_patch`. - - `"incomplete"` + - `"apply_patch"` - - `type: "shell_call_output"` + - `type: "tool_search_output"` - The type of the shell call output. Always `shell_call_output`. + The type of the item. Always `tool_search_output`. - - `"shell_call_output"` + - `"tool_search_output"` - `created_by: optional string` The identifier of the actor that created the item. - - `ApplyPatchCall object { id, call_id, operation, 3 more }` - - A tool call that applies file diffs by creating, deleting, or updating files. + - `AdditionalTools object { id, role, tools, type }` - `id: string` - The unique ID of the apply patch tool call. Populated when this item is returned via API. - - - `call_id: string` - - The unique ID of the apply patch tool call generated by the model. + The unique ID of the additional tools item. - - `operation: object { diff, path, type } or object { path, type } or object { diff, path, type }` + - `role: "unknown" or "user" or "assistant" or 5 more` - One of the create_file, delete_file, or update_file operations applied via apply_patch. + The role that provided the additional tools. - - `CreateFile object { diff, path, type }` + - `"unknown"` - Instruction describing how to create a file via the apply_patch tool. + - `"user"` - - `diff: string` + - `"assistant"` - Diff to apply. + - `"system"` - - `path: string` + - `"critic"` - Path of the file to create. + - `"discriminator"` - - `type: "create_file"` + - `"developer"` - Create a new file with the provided diff. + - `"tool"` - - `"create_file"` + - `tools: array of object { name, parameters, strict, 3 more } or object { type, vector_store_ids, filters, 2 more } or object { type } or 12 more` - - `DeleteFile object { path, type }` + The additional tool definitions made available at this item. - Instruction describing how to delete a file via the apply_patch tool. + - `Function object { name, parameters, strict, 3 more }` - - `path: string` + 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). - Path of the file to delete. + - `name: string` - - `type: "delete_file"` + The name of the function to call. - Delete the specified file. + - `parameters: map[unknown]` - - `"delete_file"` + A JSON schema object describing the parameters of the function. - - `UpdateFile object { diff, path, type }` + - `strict: boolean` - Instruction describing how to update a file via the apply_patch tool. + Whether to enforce strict parameter validation. Default `true`. - - `diff: string` + - `type: "function"` - Diff to apply. + The type of the function tool. Always `function`. - - `path: string` + - `"function"` - Path of the file to update. + - `defer_loading: optional boolean` - - `type: "update_file"` + Whether this function is deferred and loaded via tool search. - Update an existing file with the provided diff. + - `description: optional string` - - `"update_file"` + A description of the function. Used by the model to determine whether or not to call the function. - - `status: "in_progress" or "completed"` + - `FileSearch object { type, vector_store_ids, filters, 2 more }` - The status of the apply patch tool call. One of `in_progress` or `completed`. + 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). - - `"in_progress"` + - `type: "file_search"` - - `"completed"` + The type of the file search tool. Always `file_search`. - - `type: "apply_patch_call"` + - `"file_search"` - The type of the item. Always `apply_patch_call`. + - `vector_store_ids: array of string` - - `"apply_patch_call"` + The IDs of the vector stores to search. - - `created_by: optional string` + - `filters: optional ComparisonFilter or CompoundFilter` - The ID of the entity that created this tool call. + A filter to apply. - - `ApplyPatchCallOutput object { id, call_id, status, 3 more }` + - `ComparisonFilter object { key, type, value }` - The output emitted by an apply patch tool call. + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - - `id: string` + - `CompoundFilter object { filters, type }` - The unique ID of the apply patch tool call output. Populated when this item is returned via API. + Combine multiple filters using `and` or `or`. - - `call_id: string` + - `max_num_results: optional number` - The unique ID of the apply patch tool call generated by the model. + The maximum number of results to return. This number should be between 1 and 50 inclusive. - - `status: "completed" or "failed"` + - `ranking_options: optional object { hybrid_search, ranker, score_threshold }` - The status of the apply patch tool call output. One of `completed` or `failed`. + Ranking options for search. - - `"completed"` + - `hybrid_search: optional object { embedding_weight, text_weight }` - - `"failed"` + Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. - - `type: "apply_patch_call_output"` + - `embedding_weight: number` - The type of the item. Always `apply_patch_call_output`. + The weight of the embedding in the reciprocal ranking fusion. - - `"apply_patch_call_output"` + - `text_weight: number` - - `created_by: optional string` + The weight of the text in the reciprocal ranking fusion. - The ID of the entity that created this tool call output. + - `ranker: optional "auto" or "default-2024-11-15"` - - `output: optional string` + The ranker to use for the file search. - Optional textual output returned by the apply patch tool. + - `"auto"` - - `McpListTools object { id, server_label, tools, 2 more }` + - `"default-2024-11-15"` - A list of tools available on an MCP server. + - `score_threshold: optional number` - - `id: string` + The score threshold for the file search, a number between 0 and 1. Numbers closer to 1 will attempt to return only the most relevant results, but may return fewer results. - The unique ID of the list. + - `Computer object { type }` - - `server_label: string` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - The label of the MCP server. + - `type: "computer"` - - `tools: array of object { input_schema, name, annotations, description }` + The type of the computer tool. Always `computer`. - The tools available on the server. + - `"computer"` - - `input_schema: unknown` + - `ComputerUsePreview object { display_height, display_width, environment, type }` - The JSON schema describing the tool's input. + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `name: string` + - `display_height: number` - The name of the tool. + The height of the computer display. - - `annotations: optional unknown` + - `display_width: number` - Additional annotations about the tool. + The width of the computer display. - - `description: optional string` + - `environment: "windows" or "mac" or "linux" or 2 more` - The description of the tool. + The type of computer environment to control. - - `type: "mcp_list_tools"` + - `"windows"` - The type of the item. Always `mcp_list_tools`. + - `"mac"` - - `"mcp_list_tools"` + - `"linux"` - - `error: optional string` + - `"ubuntu"` - Error message if the server could not list tools. + - `"browser"` - - `McpApprovalRequest object { id, arguments, name, 2 more }` + - `type: "computer_use_preview"` - A request for human approval of a tool invocation. + The type of the computer use tool. Always `computer_use_preview`. - - `id: string` + - `"computer_use_preview"` - The unique ID of the approval request. + - `WebSearch object { type, filters, search_context_size, user_location }` - - `arguments: string` + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](/docs/guides/tools-web-search). - A JSON string of arguments for the tool. + - `type: "web_search" or "web_search_2025_08_26"` - - `name: string` + The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. - The name of the tool to run. + - `"web_search"` - - `server_label: string` + - `"web_search_2025_08_26"` - The label of the MCP server making the request. + - `filters: optional object { allowed_domains }` - - `type: "mcp_approval_request"` + Filters for the search. - The type of the item. Always `mcp_approval_request`. + - `allowed_domains: optional array of string` - - `"mcp_approval_request"` + Allowed domains for the search. If not provided, all domains are allowed. + Subdomains of the provided domains are allowed as well. - - `McpApprovalResponse object { id, approval_request_id, approve, 2 more }` + Example: `["pubmed.ncbi.nlm.nih.gov"]` - A response to an MCP approval request. + - `search_context_size: optional "low" or "medium" or "high"` - - `id: string` + High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. - The unique ID of the approval response + - `"low"` - - `approval_request_id: string` + - `"medium"` - The ID of the approval request being answered. + - `"high"` - - `approve: boolean` + - `user_location: optional object { city, country, region, 2 more }` - Whether the request was approved. + The approximate location of the user. - - `type: "mcp_approval_response"` + - `city: optional string` - The type of the item. Always `mcp_approval_response`. + Free text input for the city of the user, e.g. `San Francisco`. - - `"mcp_approval_response"` + - `country: optional string` - - `reason: optional string` + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - Optional reason for the decision. + - `region: optional string` - - `McpCall object { id, arguments, name, 6 more }` + Free text input for the region of the user, e.g. `California`. - An invocation of a tool on an MCP server. + - `timezone: optional string` - - `id: string` + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - The unique ID of the tool call. + - `type: optional "approximate"` - - `arguments: string` + The type of location approximation. Always `approximate`. - A JSON string of the arguments passed to the tool. + - `"approximate"` - - `name: string` + - `Mcp object { server_label, type, allowed_tools, 7 more }` - The name of the tool that was run. + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](/docs/guides/tools-remote-mcp). - `server_label: string` - The label of the MCP server running the tool. + A label for this MCP server, used to identify it in tool calls. - - `type: "mcp_call"` + - `type: "mcp"` - The type of the item. Always `mcp_call`. + The type of the MCP tool. Always `mcp`. - - `"mcp_call"` + - `"mcp"` - - `approval_request_id: optional string` + - `allowed_tools: optional array of string or object { read_only, tool_names }` - Unique identifier for the MCP tool call approval request. - Include this value in a subsequent `mcp_approval_response` input to approve or reject the corresponding tool call. + List of allowed tool names or a filter object. - - `error: optional string` + - `McpAllowedTools = array of string` - The error from the tool call, if any. + A string array of allowed tool names - - `output: optional string` + - `McpToolFilter object { read_only, tool_names }` - The output from the tool call. + A filter object to specify which tools are allowed. - - `status: optional "in_progress" or "completed" or "incomplete" or 2 more` + - `read_only: optional boolean` - The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. - - `"in_progress"` + - `tool_names: optional array of string` - - `"completed"` + List of allowed tool names. - - `"incomplete"` + - `authorization: optional string` - - `"calling"` + An OAuth access token that can be used with a remote MCP server, either + with a custom MCP server URL or a service connector. Your application + must handle the OAuth authorization flow and provide the token here. - - `"failed"` + - `connector_id: optional "connector_dropbox" or "connector_gmail" or "connector_googlecalendar" or 5 more` - - `CustomToolCall object { call_id, input, name, 3 more }` + Identifier for service connectors, like those available in ChatGPT. One of + `server_url` or `connector_id` must be provided. Learn more about service + connectors [here](/docs/guides/tools-remote-mcp#connectors). - A call to a custom tool created by the model. + Currently supported `connector_id` values are: - - `call_id: string` + - Dropbox: `connector_dropbox` + - Gmail: `connector_gmail` + - Google Calendar: `connector_googlecalendar` + - Google Drive: `connector_googledrive` + - Microsoft Teams: `connector_microsoftteams` + - Outlook Calendar: `connector_outlookcalendar` + - Outlook Email: `connector_outlookemail` + - SharePoint: `connector_sharepoint` - An identifier used to map this custom tool call to a tool call output. + - `"connector_dropbox"` - - `input: string` + - `"connector_gmail"` - The input for the custom tool call generated by the model. + - `"connector_googlecalendar"` - - `name: string` + - `"connector_googledrive"` - The name of the custom tool being called. + - `"connector_microsoftteams"` - - `type: "custom_tool_call"` + - `"connector_outlookcalendar"` - The type of the custom tool call. Always `custom_tool_call`. + - `"connector_outlookemail"` - - `"custom_tool_call"` + - `"connector_sharepoint"` - - `id: optional string` + - `defer_loading: optional boolean` - The unique ID of the custom tool call in the OpenAI platform. + Whether this MCP tool is deferred and discovered via tool search. - - `namespace: optional string` + - `headers: optional map[string]` - The namespace of the custom tool being called. + Optional HTTP headers to send to the MCP server. Use for authentication + or other purposes. - - `CustomToolCallOutput object { call_id, output, type, id }` + - `require_approval: optional object { always, never } or "always" or "never"` - The output of a custom tool call from your code, being sent back to the model. + Specify which of the MCP server's tools require approval. - - `call_id: string` + - `McpToolApprovalFilter object { always, never }` - The call ID, used to map this custom tool call output to a custom tool call. + Specify which of the MCP server's tools require approval. Can be + `always`, `never`, or a filter object associated with tools + that require approval. - - `output: string or array of ResponseInputText or ResponseInputImage or ResponseInputFile` + - `always: optional object { read_only, tool_names }` - The output from the custom tool call generated by your code. - Can be a string or an list of output content. + A filter object to specify which tools are allowed. - - `StringOutput = string` + - `read_only: optional boolean` - A string of the output of the custom tool call. + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. - - `OutputContentList = array of ResponseInputText or ResponseInputImage or ResponseInputFile` + - `tool_names: optional array of string` - Text, image, or file output of the custom tool call. + List of allowed tool names. - - `ResponseInputText object { text, type }` + - `never: optional object { read_only, tool_names }` - A text input to the model. + A filter object to specify which tools are allowed. - - `ResponseInputImage object { detail, type, file_id, image_url }` + - `read_only: optional boolean` - An image input to the model. Learn about [image inputs](/docs/guides/vision). + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. - - `ResponseInputFile object { type, detail, file_data, 3 more }` + - `tool_names: optional array of string` - A file input to the model. + List of allowed tool names. - - `type: "custom_tool_call_output"` + - `McpToolApprovalSetting = "always" or "never"` - The type of the custom tool call output. Always `custom_tool_call_output`. + Specify a single approval policy for all tools. One of `always` or + `never`. When set to `always`, all tools will require approval. When + set to `never`, all tools will not require approval. - - `"custom_tool_call_output"` + - `"always"` - - `id: optional string` + - `"never"` - The unique ID of the custom tool call output in the OpenAI platform. + - `server_description: optional string` - - `first_id: string` + Optional description of the MCP server, used to provide more context. - The ID of the first item in the list. + - `server_url: optional string` - - `has_more: boolean` + The URL for the MCP server. One of `server_url` or `connector_id` must be + provided. - Whether there are more items available. + - `CodeInterpreter object { container, type }` - - `last_id: string` + A tool that runs Python code to help generate a response to a prompt. - The ID of the last item in the list. + - `container: string or object { type, file_ids, memory_limit, network_policy }` - - `object: "list"` + The code interpreter container. Can be a container ID or an object that + specifies uploaded file IDs to make available to your code, along with an + optional `memory_limit` setting. - The type of object returned, must be `list`. + - `string` - - `"list"` + The container ID. -### Example + - `CodeInterpreterToolAuto object { type, file_ids, memory_limit, network_policy }` -```http -curl https://api.openai.com/v1/conversations/$CONVERSATION_ID/items \ - -H "Authorization: Bearer $OPENAI_API_KEY" -``` + Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. -#### Response + - `type: "auto"` -```json -{ - "data": [ - { - "id": "id", - "content": [ - { - "text": "text", - "type": "input_text" - } - ], - "role": "unknown", - "status": "in_progress", - "type": "message", - "phase": "commentary" - } - ], - "first_id": "first_id", - "has_more": true, - "last_id": "last_id", - "object": "list" -} -``` + Always `auto`. -### Example + - `"auto"` -```http -curl "https://api.openai.com/v1/conversations/conv_123/items?limit=10" \ - -H "Authorization: Bearer $OPENAI_API_KEY" -``` + - `file_ids: optional array of string` -#### Response + An optional list of uploaded files to make available to your code. -```json -{ - "object": "list", - "data": [ - { - "type": "message", - "id": "msg_abc", - "status": "completed", - "role": "user", - "content": [ - {"type": "input_text", "text": "Hello!"} - ] - } - ], - "first_id": "msg_abc", - "last_id": "msg_abc", - "has_more": false -} -``` + - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` -## Retrieve an item + The memory limit for the code interpreter container. -**get** `/conversations/{conversation_id}/items/{item_id}` + - `"1g"` -Get a single item from a conversation with the given IDs. + - `"4g"` -### Path Parameters + - `"16g"` + + - `"64g"` -- `conversation_id: string` + - `network_policy: optional ContainerNetworkPolicyDisabled or ContainerNetworkPolicyAllowlist` -- `item_id: string` + Network access policy for the container. -### Query Parameters + - `ContainerNetworkPolicyDisabled object { type }` -- `include: optional array of ResponseIncludable` + - `ContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` - 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. + - `type: "code_interpreter"` - - `"file_search_call.results"` + The type of the code interpreter tool. Always `code_interpreter`. - - `"web_search_call.results"` + - `"code_interpreter"` - - `"web_search_call.action.sources"` + - `ImageGeneration object { type, action, background, 9 more }` - - `"message.input_image.image_url"` + A tool that generates images using the GPT image models. - - `"computer_call_output.output.image_url"` + - `type: "image_generation"` - - `"code_interpreter_call.outputs"` + The type of the image generation tool. Always `image_generation`. - - `"reasoning.encrypted_content"` + - `"image_generation"` - - `"message.output_text.logprobs"` + - `action: optional "generate" or "edit" or "auto"` -### Returns + Whether to generate a new image or edit an existing image. Default: `auto`. -- `ConversationItem = Message or object { id, arguments, call_id, 5 more } or object { id, call_id, output, 3 more } or 22 more` + - `"generate"` - 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). + - `"edit"` - - `Message object { id, content, role, 3 more }` + - `"auto"` - A message to or from the model. + - `background: optional "transparent" or "opaque" or "auto"` - - `id: string` + Background type for the generated image. One of `transparent`, + `opaque`, or `auto`. Default: `auto`. - The unique ID of the message. + - `"transparent"` - - `content: array of ResponseInputText or ResponseOutputText or TextContent or 6 more` + - `"opaque"` - The content of the message + - `"auto"` - - `ResponseInputText object { text, type }` + - `input_fidelity: optional "high" or "low"` - A text input to the model. + Control how much effort the model will exert to match the style and features, especially facial features, of input images. This parameter is only supported for `gpt-image-1` and `gpt-image-1.5` and later models, unsupported for `gpt-image-1-mini`. Supports `high` and `low`. Defaults to `low`. - - `text: string` + - `"high"` - The text input to the model. + - `"low"` - - `type: "input_text"` + - `input_image_mask: optional object { file_id, image_url }` - The type of the input item. Always `input_text`. + Optional mask for inpainting. Contains `image_url` + (string, optional) and `file_id` (string, optional). - - `"input_text"` + - `file_id: optional string` - - `ResponseOutputText object { annotations, logprobs, text, type }` + File ID for the mask image. - A text output from the model. + - `image_url: optional string` - - `annotations: array of object { file_id, filename, index, type } or object { end_index, start_index, title, 2 more } or object { container_id, end_index, file_id, 3 more } or object { file_id, index, type }` + Base64-encoded mask image. - The annotations of the text output. + - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` - - `FileCitation object { file_id, filename, index, type }` + The image generation model to use. Default: `gpt-image-1`. - A citation to a file. + - `string` - - `file_id: string` + - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` - The ID of the file. + The image generation model to use. Default: `gpt-image-1`. - - `filename: string` + - `"gpt-image-1"` - The filename of the file cited. + - `"gpt-image-1-mini"` - - `index: number` + - `"gpt-image-1.5"` - The index of the file in the list of files. + - `moderation: optional "auto" or "low"` - - `type: "file_citation"` + Moderation level for the generated image. Default: `auto`. - The type of the file citation. Always `file_citation`. + - `"auto"` - - `"file_citation"` + - `"low"` - - `URLCitation object { end_index, start_index, title, 2 more }` + - `output_compression: optional number` - A citation for a web resource used to generate a model response. + Compression level for the output image. Default: 100. - - `end_index: number` + - `output_format: optional "png" or "webp" or "jpeg"` - The index of the last character of the URL citation in the message. + The output format of the generated image. One of `png`, `webp`, or + `jpeg`. Default: `png`. - - `start_index: number` + - `"png"` - The index of the first character of the URL citation in the message. + - `"webp"` - - `title: string` + - `"jpeg"` - The title of the web resource. + - `partial_images: optional number` - - `type: "url_citation"` + Number of partial images to generate in streaming mode, from 0 (default value) to 3. - The type of the URL citation. Always `url_citation`. + - `quality: optional "low" or "medium" or "high" or "auto"` - - `"url_citation"` + The quality of the generated image. One of `low`, `medium`, `high`, + or `auto`. Default: `auto`. - - `url: string` + - `"low"` - The URL of the web resource. + - `"medium"` - - `ContainerFileCitation object { container_id, end_index, file_id, 3 more }` + - `"high"` - A citation for a container file used to generate a model response. + - `"auto"` - - `container_id: string` + - `size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or "auto"` - The ID of the container file. + The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. - - `end_index: number` + - `string` - The index of the last character of the container file citation in the message. + - `"1024x1024" or "1024x1536" or "1536x1024" or "auto"` - - `file_id: string` + The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. - The ID of the file. + - `"1024x1024"` - - `filename: string` + - `"1024x1536"` - The filename of the container file cited. + - `"1536x1024"` - - `start_index: number` + - `"auto"` - The index of the first character of the container file citation in the message. + - `LocalShell object { type }` - - `type: "container_file_citation"` + A tool that allows the model to execute shell commands in a local environment. - The type of the container file citation. Always `container_file_citation`. + - `type: "local_shell"` - - `"container_file_citation"` + The type of the local shell tool. Always `local_shell`. - - `FilePath object { file_id, index, type }` + - `"local_shell"` - A path to a file. + - `Shell object { type, environment }` - - `file_id: string` + A tool that allows the model to execute shell commands. - The ID of the file. + - `type: "shell"` - - `index: number` + The type of the shell tool. Always `shell`. - The index of the file in the list of files. + - `"shell"` - - `type: "file_path"` + - `environment: optional ContainerAuto or LocalEnvironment or ContainerReference` - The type of the file path. Always `file_path`. + - `ContainerAuto object { type, file_ids, memory_limit, 2 more }` - - `"file_path"` + - `LocalEnvironment object { type, skills }` - - `logprobs: array of object { token, bytes, logprob, top_logprobs }` + - `ContainerReference object { container_id, type }` - - `token: string` + - `Custom object { name, type, defer_loading, 2 more }` - - `bytes: array of number` + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) - - `logprob: number` + - `name: string` - - `top_logprobs: array of object { token, bytes, logprob }` + The name of the custom tool, used to identify it in tool calls. - - `token: string` + - `type: "custom"` - - `bytes: array of number` + The type of the custom tool. Always `custom`. - - `logprob: number` + - `"custom"` - - `text: string` + - `defer_loading: optional boolean` - The text output from the model. + Whether this tool should be deferred and discovered via tool search. - - `type: "output_text"` + - `description: optional string` - The type of the output text. Always `output_text`. + Optional description of the custom tool, used to provide more context. - - `"output_text"` + - `format: optional CustomToolInputFormat` - - `TextContent object { text, type }` + The input format for the custom tool. Default is unconstrained text. - A text content. + - `Namespace object { description, name, tools, type }` - - `text: string` + Groups function/custom tools under a shared namespace. - - `type: "text"` + - `description: string` - - `"text"` + A description of the namespace shown to the model. - - `SummaryTextContent object { text, type }` + - `name: string` - A summary text from the model. + The namespace name used in tool calls (for example, `crm`). - - `text: string` + - `tools: array of object { name, type, defer_loading, 3 more } or object { name, type, defer_loading, 2 more }` - A summary of the reasoning output from the model so far. + The function/custom tools available inside this namespace. - - `type: "summary_text"` + - `Function object { name, type, defer_loading, 3 more }` - The type of the object. Always `summary_text`. + - `name: string` - - `"summary_text"` + - `type: "function"` - - `ReasoningText object { text, type }` + - `"function"` - Reasoning text from the model. + - `defer_loading: optional boolean` - - `text: string` + Whether this function should be deferred and discovered via tool search. - The reasoning text from the model. + - `description: optional string` - - `type: "reasoning_text"` + - `parameters: optional unknown` - The type of the reasoning text. Always `reasoning_text`. + - `strict: optional boolean` - - `"reasoning_text"` + - `Custom object { name, type, defer_loading, 2 more }` - - `ResponseOutputRefusal object { refusal, type }` + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) - A refusal from the model. + - `name: string` - - `refusal: string` + The name of the custom tool, used to identify it in tool calls. - The refusal explanation from the model. + - `type: "custom"` - - `type: "refusal"` + The type of the custom tool. Always `custom`. - The type of the refusal. Always `refusal`. + - `"custom"` - - `"refusal"` + - `defer_loading: optional boolean` - - `ResponseInputImage object { detail, type, file_id, image_url }` + Whether this tool should be deferred and discovered via tool search. - An image input to the model. Learn about [image inputs](/docs/guides/vision). + - `description: optional string` - - `detail: "low" or "high" or "auto" or "original"` + Optional description of the custom tool, used to provide more context. - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + - `format: optional CustomToolInputFormat` - - `"low"` + The input format for the custom tool. Default is unconstrained text. - - `"high"` + - `type: "namespace"` - - `"auto"` + The type of the tool. Always `namespace`. - - `"original"` + - `"namespace"` - - `type: "input_image"` + - `ToolSearch object { type, description, execution, parameters }` - The type of the input item. Always `input_image`. + Hosted or BYOT tool search configuration for deferred tools. - - `"input_image"` + - `type: "tool_search"` - - `file_id: optional string` + The type of the tool. Always `tool_search`. - The ID of the file to be sent to the model. + - `"tool_search"` - - `image_url: optional string` + - `description: optional string` - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + Description shown to the model for a client-executed tool search tool. - - `ComputerScreenshotContent object { detail, file_id, image_url, type }` + - `execution: optional "server" or "client"` - A screenshot of a computer. + Whether tool search is executed by the server or by the client. - - `detail: "low" or "high" or "auto" or "original"` + - `"server"` - The detail level of the screenshot image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + - `"client"` - - `"low"` + - `parameters: optional unknown` - - `"high"` + Parameter schema for a client-executed tool search tool. - - `"auto"` + - `WebSearchPreview object { type, search_content_types, search_context_size, user_location }` - - `"original"` + This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - - `file_id: string` + - `type: "web_search_preview" or "web_search_preview_2025_03_11"` - The identifier of an uploaded file that contains the screenshot. + The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. - - `image_url: string` + - `"web_search_preview"` - The URL of the screenshot image. + - `"web_search_preview_2025_03_11"` - - `type: "computer_screenshot"` + - `search_content_types: optional array of "text" or "image"` - Specifies the event type. For a computer screenshot, this property is always set to `computer_screenshot`. + - `"text"` - - `"computer_screenshot"` + - `"image"` - - `ResponseInputFile object { type, detail, file_data, 3 more }` + - `search_context_size: optional "low" or "medium" or "high"` - A file input to the model. + High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. - - `type: "input_file"` + - `"low"` - The type of the input item. Always `input_file`. + - `"medium"` - - `"input_file"` + - `"high"` - - `detail: optional "low" or "high"` + - `user_location: optional object { type, city, country, 2 more }` - 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 user's location. - - `"low"` + - `type: "approximate"` - - `"high"` + The type of location approximation. Always `approximate`. - - `file_data: optional string` + - `"approximate"` - The content of the file to be sent to the model. + - `city: optional string` - - `file_id: optional string` + Free text input for the city of the user, e.g. `San Francisco`. - The ID of the file to be sent to the model. + - `country: optional string` - - `file_url: optional string` + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - The URL of the file to be sent to the model. + - `region: optional string` - - `filename: optional string` + Free text input for the region of the user, e.g. `California`. - The name of the file to be sent to the model. + - `timezone: optional string` - - `role: "unknown" or "user" or "assistant" or 5 more` + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - The role of the message. One of `unknown`, `user`, `assistant`, `system`, `critic`, `discriminator`, `developer`, or `tool`. + - `ApplyPatch object { type }` - - `"unknown"` + Allows the assistant to create, delete, or update files using unified diffs. - - `"user"` + - `type: "apply_patch"` - - `"assistant"` + The type of the tool. Always `apply_patch`. - - `"system"` + - `"apply_patch"` - - `"critic"` + - `type: "additional_tools"` - - `"discriminator"` + The type of the item. Always `additional_tools`. - - `"developer"` + - `"additional_tools"` - - `"tool"` + - `Reasoning object { id, summary, type, 3 more }` - - `status: "in_progress" or "completed" or "incomplete"` + 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). - The status of item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. + - `id: string` - - `"in_progress"` + The unique identifier of the reasoning content. - - `"completed"` + - `summary: array of SummaryTextContent` - - `"incomplete"` + Reasoning summary content. - - `type: "message"` + - `text: string` - The type of the message. Always set to `message`. + A summary of the reasoning output from the model so far. - - `"message"` + - `type: "summary_text"` - - `phase: optional "commentary" or "final_answer"` + The type of the object. Always `summary_text`. - Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend phase on all assistant messages — dropping it can degrade performance. Not used for user messages. + - `type: "reasoning"` - - `"commentary"` + The type of the object. Always `reasoning`. - - `"final_answer"` + - `"reasoning"` - - `FunctionCall object { id, arguments, call_id, 5 more }` + - `content: optional array of object { text, type }` - - `id: string` + Reasoning text content. - The unique ID of the function tool call. + - `text: string` - - `arguments: string` + The reasoning text from the model. - A JSON string of the arguments to pass to the function. + - `type: "reasoning_text"` - - `call_id: string` + The type of the reasoning text. Always `reasoning_text`. - The unique ID of the function tool call generated by the model. + - `"reasoning_text"` - - `name: string` + - `encrypted_content: optional string` - The name of the function to run. + The encrypted content of the reasoning item - populated when a response is + generated with `reasoning.encrypted_content` in the `include` parameter. - - `status: "in_progress" or "completed" or "incomplete"` + - `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. @@ -12670,59 +18161,80 @@ Get a single item from a conversation with the given IDs. - `"incomplete"` - - `type: "function_call"` + - `Compaction object { id, encrypted_content, type, created_by }` - The type of the function tool call. Always `function_call`. + A compaction item generated by the [`v1/responses/compact` API](/docs/api-reference/responses/compact). - - `"function_call"` + - `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`. + + - `"compaction"` - `created_by: optional string` The identifier of the actor that created the item. - - `namespace: optional string` - - The namespace of the function to run. + - `CodeInterpreterCall object { id, code, container_id, 3 more }` - - `FunctionCallOutput object { id, call_id, output, 3 more }` + A tool call to run code. - `id: string` - The unique ID of the function call tool output. + The unique ID of the code interpreter tool call. - - `call_id: string` + - `code: string` - The unique ID of the function tool call generated by the model. + The code to run, or null if not available. - - `output: string or array of ResponseInputText or ResponseInputImage or ResponseInputFile` + - `container_id: string` - The output from the function call generated by your code. - Can be a string or an list of output content. + The ID of the container used to run the code. - - `StringOutput = string` + - `outputs: array of object { logs, type } or object { type, url }` - A string of the output of the function call. + The outputs generated by the code interpreter, such as logs or images. + Can be null if no outputs are available. - - `OutputContentList = array of ResponseInputText or ResponseInputImage or ResponseInputFile` + - `Logs object { logs, type }` - Text, image, or file output of the function call. + The logs output from the code interpreter. - - `ResponseInputText object { text, type }` + - `logs: string` - A text input to the model. + The logs output from the code interpreter. - - `ResponseInputImage object { detail, type, file_id, image_url }` + - `type: "logs"` - An image input to the model. Learn about [image inputs](/docs/guides/vision). + The type of the output. Always `logs`. - - `ResponseInputFile object { type, detail, file_data, 3 more }` + - `"logs"` - A file input to the model. + - `Image object { type, url }` - - `status: "in_progress" or "completed" or "incomplete"` + The image output from the code interpreter. - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `type: "image"` + + The type of the output. Always `image`. + + - `"image"` + + - `url: string` + + The URL of the image output from the code interpreter. + + - `status: "in_progress" or "completed" or "incomplete" or 2 more` + + The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. - `"in_progress"` @@ -12730,243 +18242,237 @@ Get a single item from a conversation with the given IDs. - `"incomplete"` - - `type: "function_call_output"` + - `"interpreting"` - The type of the function tool call output. Always `function_call_output`. + - `"failed"` - - `"function_call_output"` + - `type: "code_interpreter_call"` - - `created_by: optional string` + The type of the code interpreter tool call. Always `code_interpreter_call`. - The identifier of the actor that created the item. + - `"code_interpreter_call"` - - `FileSearchCall object { id, queries, status, 2 more }` + - `LocalShellCall object { id, action, call_id, 2 more }` - The results of a file search tool call. See the - [file search guide](/docs/guides/tools-file-search) for more information. + A tool call to run a command on the local shell. - `id: string` - The unique ID of the file search tool call. - - - `queries: array of string` - - The queries used to search for files. + The unique ID of the local shell call. - - `status: "in_progress" or "searching" or "completed" or 2 more` + - `action: object { command, env, type, 3 more }` - The status of the file search tool call. One of `in_progress`, - `searching`, `incomplete` or `failed`, + Execute a shell command on the server. - - `"in_progress"` + - `command: array of string` - - `"searching"` + The command to run. - - `"completed"` + - `env: map[string]` - - `"incomplete"` + Environment variables to set for the command. - - `"failed"` + - `type: "exec"` - - `type: "file_search_call"` + The type of the local shell action. Always `exec`. - The type of the file search tool call. Always `file_search_call`. + - `"exec"` - - `"file_search_call"` + - `timeout_ms: optional number` - - `results: optional array of object { attributes, file_id, filename, 2 more }` + Optional timeout in milliseconds for the command. - The results of the file search tool call. + - `user: optional string` - - `attributes: optional map[string or number or boolean]` + Optional user to run the command as. - Set of 16 key-value pairs that can be attached to an object. This can be - useful for storing additional information about the object in a structured - format, and querying for objects via API or the dashboard. Keys are strings - with a maximum length of 64 characters. Values are strings with a maximum - length of 512 characters, booleans, or numbers. + - `working_directory: optional string` - - `string` + Optional working directory to run the command in. - - `number` + - `call_id: string` - - `boolean` + The unique ID of the local shell tool call generated by the model. - - `file_id: optional string` + - `status: "in_progress" or "completed" or "incomplete"` - The unique ID of the file. + The status of the local shell call. - - `filename: optional string` + - `"in_progress"` - The name of the file. + - `"completed"` - - `score: optional number` + - `"incomplete"` - The relevance score of the file - a value between 0 and 1. + - `type: "local_shell_call"` - - `text: optional string` + The type of the local shell call. Always `local_shell_call`. - The text that was retrieved from the file. + - `"local_shell_call"` - - `WebSearchCall object { id, action, status, type }` + - `LocalShellCallOutput object { id, output, type, status }` - The results of a web search tool call. See the - [web search guide](/docs/guides/tools-web-search) for more information. + The output of a local shell tool call. - `id: string` - The unique ID of the web search tool call. + The unique ID of the local shell tool call generated by the model. - - `action: object { query, type, queries, sources } or object { type, url } or object { pattern, type, url }` + - `output: string` - An object describing the specific action taken in this web search call. - Includes details on how the model used the web (search, open_page, find_in_page). + A JSON string of the output of the local shell tool call. - - `Search object { query, type, queries, sources }` + - `type: "local_shell_call_output"` - Action type "search" - Performs a web search query. + The type of the local shell tool call output. Always `local_shell_call_output`. - - `query: string` + - `"local_shell_call_output"` - [DEPRECATED] The search query. + - `status: optional "in_progress" or "completed" or "incomplete"` - - `type: "search"` + The status of the item. One of `in_progress`, `completed`, or `incomplete`. - The action type. + - `"in_progress"` - - `"search"` + - `"completed"` - - `queries: optional array of string` + - `"incomplete"` - The search queries. + - `ShellCall object { id, action, call_id, 4 more }` - - `sources: optional array of object { type, url }` + A tool call that executes one or more shell commands in a managed environment. - The sources used in the search. + - `id: string` - - `type: "url"` + The unique ID of the shell tool call. Populated when this item is returned via API. - The type of source. Always `url`. + - `action: object { commands, max_output_length, timeout_ms }` - - `"url"` + The shell commands and limits that describe how to run the tool call. - - `url: string` + - `commands: array of string` - The URL of the source. + - `max_output_length: number` - - `OpenPage object { type, url }` + Optional maximum number of characters to return from each command. - Action type "open_page" - Opens a specific URL from search results. + - `timeout_ms: number` - - `type: "open_page"` + Optional timeout in milliseconds for the commands. - The action type. + - `call_id: string` - - `"open_page"` + The unique ID of the shell tool call generated by the model. - - `url: optional string` + - `environment: ResponseLocalEnvironment or ResponseContainerReference` - The URL opened by the model. + Represents the use of a local environment to perform shell actions. - - `FindInPage object { pattern, type, url }` + - `ResponseLocalEnvironment object { type }` - Action type "find_in_page": Searches for a pattern within a loaded page. + Represents the use of a local environment to perform shell actions. - - `pattern: string` + - `type: "local"` - The pattern or text to search for within the page. + The environment type. Always `local`. - - `type: "find_in_page"` + - `"local"` - The action type. + - `ResponseContainerReference object { container_id, type }` - - `"find_in_page"` + Represents a container created with /v1/containers. - - `url: string` + - `container_id: string` - The URL of the page searched for the pattern. + - `type: "container_reference"` - - `status: "in_progress" or "searching" or "completed" or "failed"` + The environment type. Always `container_reference`. - The status of the web search tool call. + - `"container_reference"` - - `"in_progress"` + - `status: "in_progress" or "completed" or "incomplete"` - - `"searching"` + The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. + + - `"in_progress"` - `"completed"` - - `"failed"` + - `"incomplete"` - - `type: "web_search_call"` + - `type: "shell_call"` - The type of the web search tool call. Always `web_search_call`. + The type of the item. Always `shell_call`. - - `"web_search_call"` + - `"shell_call"` - - `ImageGenerationCall object { id, result, status, type }` + - `created_by: optional string` - An image generation request made by the model. + The ID of the entity that created this tool call. + + - `ShellCallOutput object { id, call_id, max_output_length, 4 more }` + + The output of a shell tool call that was emitted. - `id: string` - The unique ID of the image generation call. + The unique ID of the shell call output. Populated when this item is returned via API. - - `result: string` + - `call_id: string` - The generated image encoded in base64. + The unique ID of the shell tool call generated by the model. - - `status: "in_progress" or "completed" or "generating" or "failed"` + - `max_output_length: number` - The status of the image generation call. + The maximum length of the shell command output. This is generated by the model and should be passed back with the raw output. - - `"in_progress"` + - `output: array of object { outcome, stderr, stdout, created_by }` - - `"completed"` + An array of shell call output contents - - `"generating"` + - `outcome: object { type } or object { exit_code, type }` - - `"failed"` + Represents either an exit outcome (with an exit code) or a timeout outcome for a shell call output chunk. - - `type: "image_generation_call"` + - `Timeout object { type }` - The type of the image generation call. Always `image_generation_call`. + Indicates that the shell call exceeded its configured time limit. - - `"image_generation_call"` + - `type: "timeout"` - - `ComputerCall object { id, call_id, pending_safety_checks, 4 more }` + The outcome type. Always `timeout`. - A tool call to a computer use tool. See the - [computer use guide](/docs/guides/tools-computer-use) for more information. + - `"timeout"` - - `id: string` + - `Exit object { exit_code, type }` - The unique ID of the computer call. + Indicates that the shell commands finished and returned an exit code. - - `call_id: string` + - `exit_code: number` - An identifier used when responding to the tool call with output. + Exit code from the shell process. - - `pending_safety_checks: array of object { id, code, message }` + - `type: "exit"` - The pending safety checks for the computer call. + The outcome type. Always `exit`. - - `id: string` + - `"exit"` - The ID of the pending safety check. + - `stderr: string` - - `code: optional string` + The standard error output that was captured. - The type of the pending safety check. + - `stdout: string` - - `message: optional string` + The standard output that was captured. - Details about the pending safety check. + - `created_by: optional string` + + The identifier of the actor that created the item. - `status: "in_progress" or "completed" or "incomplete"` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + The status of the shell call output. One of `in_progress`, `completed`, or `incomplete`. - `"in_progress"` @@ -12974,2529 +18480,2534 @@ Get a single item from a conversation with the given IDs. - `"incomplete"` - - `type: "computer_call"` - - The type of the computer call. Always `computer_call`. + - `type: "shell_call_output"` - - `"computer_call"` + The type of the shell call output. Always `shell_call_output`. - - `action: optional ComputerAction` + - `"shell_call_output"` - A click action. + - `created_by: optional string` - - `Click object { button, type, x, 2 more }` + The identifier of the actor that created the item. - A click action. + - `ApplyPatchCall object { id, call_id, operation, 3 more }` - - `button: "left" or "right" or "wheel" or 2 more` + A tool call that applies file diffs by creating, deleting, or updating files. - Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. + - `id: string` - - `"left"` + The unique ID of the apply patch tool call. Populated when this item is returned via API. - - `"right"` + - `call_id: string` - - `"wheel"` + The unique ID of the apply patch tool call generated by the model. - - `"back"` + - `operation: object { diff, path, type } or object { path, type } or object { diff, path, type }` - - `"forward"` + One of the create_file, delete_file, or update_file operations applied via apply_patch. - - `type: "click"` + - `CreateFile object { diff, path, type }` - Specifies the event type. For a click action, this property is always `click`. + Instruction describing how to create a file via the apply_patch tool. - - `"click"` + - `diff: string` - - `x: number` + Diff to apply. - The x-coordinate where the click occurred. + - `path: string` - - `y: number` + Path of the file to create. - The y-coordinate where the click occurred. + - `type: "create_file"` - - `keys: optional array of string` + Create a new file with the provided diff. - The keys being held while clicking. + - `"create_file"` - - `DoubleClick object { keys, type, x, y }` + - `DeleteFile object { path, type }` - A double click action. + Instruction describing how to delete a file via the apply_patch tool. - - `keys: array of string` + - `path: string` - The keys being held while double-clicking. + Path of the file to delete. - - `type: "double_click"` + - `type: "delete_file"` - Specifies the event type. For a double click action, this property is always set to `double_click`. + Delete the specified file. - - `"double_click"` + - `"delete_file"` - - `x: number` + - `UpdateFile object { diff, path, type }` - The x-coordinate where the double click occurred. + Instruction describing how to update a file via the apply_patch tool. - - `y: number` + - `diff: string` - The y-coordinate where the double click occurred. + Diff to apply. - - `Drag object { path, type, keys }` + - `path: string` - A drag action. + Path of the file to update. - - `path: array of object { x, y }` + - `type: "update_file"` - An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg + Update an existing file with the provided diff. - ``` - [ - { x: 100, y: 200 }, - { x: 200, y: 300 } - ] - ``` + - `"update_file"` - - `x: number` + - `status: "in_progress" or "completed"` - The x-coordinate. + The status of the apply patch tool call. One of `in_progress` or `completed`. - - `y: number` + - `"in_progress"` - The y-coordinate. + - `"completed"` - - `type: "drag"` + - `type: "apply_patch_call"` - Specifies the event type. For a drag action, this property is always set to `drag`. + The type of the item. Always `apply_patch_call`. - - `"drag"` + - `"apply_patch_call"` - - `keys: optional array of string` + - `created_by: optional string` - The keys being held while dragging the mouse. + The ID of the entity that created this tool call. - - `Keypress object { keys, type }` + - `ApplyPatchCallOutput object { id, call_id, status, 3 more }` - A collection of keypresses the model would like to perform. + The output emitted by an apply patch tool call. - - `keys: array of string` + - `id: string` - The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. + The unique ID of the apply patch tool call output. Populated when this item is returned via API. - - `type: "keypress"` + - `call_id: string` - Specifies the event type. For a keypress action, this property is always set to `keypress`. + The unique ID of the apply patch tool call generated by the model. - - `"keypress"` + - `status: "completed" or "failed"` - - `Move object { type, x, y, keys }` + The status of the apply patch tool call output. One of `completed` or `failed`. - A mouse move action. + - `"completed"` - - `type: "move"` + - `"failed"` - Specifies the event type. For a move action, this property is always set to `move`. + - `type: "apply_patch_call_output"` - - `"move"` + The type of the item. Always `apply_patch_call_output`. - - `x: number` + - `"apply_patch_call_output"` - The x-coordinate to move to. + - `created_by: optional string` - - `y: number` + The ID of the entity that created this tool call output. - The y-coordinate to move to. + - `output: optional string` - - `keys: optional array of string` + Optional textual output returned by the apply patch tool. - The keys being held while moving the mouse. + - `McpListTools object { id, server_label, tools, 2 more }` - - `Screenshot object { type }` + A list of tools available on an MCP server. - A screenshot action. + - `id: string` - - `type: "screenshot"` + The unique ID of the list. - Specifies the event type. For a screenshot action, this property is always set to `screenshot`. + - `server_label: string` - - `"screenshot"` + The label of the MCP server. - - `Scroll object { scroll_x, scroll_y, type, 3 more }` + - `tools: array of object { input_schema, name, annotations, description }` - A scroll action. + The tools available on the server. - - `scroll_x: number` + - `input_schema: unknown` - The horizontal scroll distance. + The JSON schema describing the tool's input. - - `scroll_y: number` + - `name: string` - The vertical scroll distance. + The name of the tool. - - `type: "scroll"` + - `annotations: optional unknown` - Specifies the event type. For a scroll action, this property is always set to `scroll`. + Additional annotations about the tool. - - `"scroll"` + - `description: optional string` - - `x: number` + The description of the tool. - The x-coordinate where the scroll occurred. + - `type: "mcp_list_tools"` - - `y: number` + The type of the item. Always `mcp_list_tools`. - The y-coordinate where the scroll occurred. + - `"mcp_list_tools"` - - `keys: optional array of string` + - `error: optional string` - The keys being held while scrolling. + Error message if the server could not list tools. - - `Type object { text, type }` + - `McpApprovalRequest object { id, arguments, name, 2 more }` - An action to type in text. + A request for human approval of a tool invocation. - - `text: string` + - `id: string` - The text to type. + The unique ID of the approval request. - - `type: "type"` + - `arguments: string` - Specifies the event type. For a type action, this property is always set to `type`. + A JSON string of arguments for the tool. - - `"type"` + - `name: string` - - `Wait object { type }` + The name of the tool to run. - A wait action. + - `server_label: string` - - `type: "wait"` + The label of the MCP server making the request. - Specifies the event type. For a wait action, this property is always set to `wait`. + - `type: "mcp_approval_request"` - - `"wait"` + The type of the item. Always `mcp_approval_request`. - - `actions: optional ComputerActionList` + - `"mcp_approval_request"` - Flattened batched actions for `computer_use`. Each action includes an - `type` discriminator and action-specific fields. + - `McpApprovalResponse object { id, approval_request_id, approve, 2 more }` - - `Click object { button, type, x, 2 more }` + A response to an MCP approval request. - A click action. + - `id: string` - - `DoubleClick object { keys, type, x, y }` + The unique ID of the approval response - A double click action. + - `approval_request_id: string` - - `Drag object { path, type, keys }` + The ID of the approval request being answered. - A drag action. + - `approve: boolean` - - `Keypress object { keys, type }` + Whether the request was approved. - A collection of keypresses the model would like to perform. + - `type: "mcp_approval_response"` - - `Move object { type, x, y, keys }` + The type of the item. Always `mcp_approval_response`. - A mouse move action. + - `"mcp_approval_response"` - - `Screenshot object { type }` + - `reason: optional string` - A screenshot action. + Optional reason for the decision. - - `Scroll object { scroll_x, scroll_y, type, 3 more }` + - `McpCall object { id, arguments, name, 6 more }` - A scroll action. + An invocation of a tool on an MCP server. - - `Type object { text, type }` + - `id: string` - An action to type in text. + The unique ID of the tool call. - - `Wait object { type }` + - `arguments: string` - A wait action. + A JSON string of the arguments passed to the tool. - - `ComputerCallOutput object { id, call_id, output, 4 more }` + - `name: string` - - `id: string` + The name of the tool that was run. - The unique ID of the computer call tool output. + - `server_label: string` - - `call_id: string` + The label of the MCP server running the tool. - The ID of the computer tool call that produced the output. + - `type: "mcp_call"` - - `output: ResponseComputerToolCallOutputScreenshot` + The type of the item. Always `mcp_call`. - A computer screenshot image used with the computer use tool. + - `"mcp_call"` - - `type: "computer_screenshot"` + - `approval_request_id: optional string` - Specifies the event type. For a computer screenshot, this property is - always set to `computer_screenshot`. + Unique identifier for the MCP tool call approval request. + Include this value in a subsequent `mcp_approval_response` input to approve or reject the corresponding tool call. - - `"computer_screenshot"` + - `error: optional string` - - `file_id: optional string` + The error from the tool call, if any. - The identifier of an uploaded file that contains the screenshot. + - `output: optional string` - - `image_url: optional string` + The output from the tool call. - The URL of the screenshot image. + - `status: optional "in_progress" or "completed" or "incomplete" or 2 more` - - `status: "completed" or "incomplete" or "failed" or "in_progress"` + The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. - The status of the message input. One of `in_progress`, `completed`, or - `incomplete`. Populated when input items are returned via API. + - `"in_progress"` - `"completed"` - `"incomplete"` - - `"failed"` - - - `"in_progress"` + - `"calling"` - - `type: "computer_call_output"` + - `"failed"` - The type of the computer tool call output. Always `computer_call_output`. + - `CustomToolCall object { call_id, input, name, 3 more }` - - `"computer_call_output"` + A call to a custom tool created by the model. - - `acknowledged_safety_checks: optional array of object { id, code, message }` + - `call_id: string` - The safety checks reported by the API that have been acknowledged by the - developer. + An identifier used to map this custom tool call to a tool call output. - - `id: string` + - `input: string` - The ID of the pending safety check. + The input for the custom tool call generated by the model. - - `code: optional string` + - `name: string` - The type of the pending safety check. + The name of the custom tool being called. - - `message: optional string` + - `type: "custom_tool_call"` - Details about the pending safety check. + The type of the custom tool call. Always `custom_tool_call`. - - `created_by: optional string` + - `"custom_tool_call"` - The identifier of the actor that created the item. + - `id: optional string` - - `ToolSearchCall object { id, arguments, call_id, 4 more }` + The unique ID of the custom tool call in the OpenAI platform. - - `id: string` + - `namespace: optional string` - The unique ID of the tool search call item. + The namespace of the custom tool being called. - - `arguments: unknown` + - `CustomToolCallOutput object { call_id, output, type, id }` - Arguments used for the tool search call. + The output of a custom tool call from your code, being sent back to the model. - `call_id: string` - The unique ID of the tool search call generated by the model. - - - `execution: "server" or "client"` + The call ID, used to map this custom tool call output to a custom tool call. - Whether tool search was executed by the server or by the client. + - `output: string or array of ResponseInputText or ResponseInputImage or ResponseInputFile` - - `"server"` + The output from the custom tool call generated by your code. + Can be a string or an list of output content. - - `"client"` + - `StringOutput = string` - - `status: "in_progress" or "completed" or "incomplete"` + A string of the output of the custom tool call. - The status of the tool search call item that was recorded. + - `OutputContentList = array of ResponseInputText or ResponseInputImage or ResponseInputFile` - - `"in_progress"` + Text, image, or file output of the custom tool call. - - `"completed"` + - `ResponseInputText object { text, type }` - - `"incomplete"` + A text input to the model. - - `type: "tool_search_call"` + - `ResponseInputImage object { detail, type, file_id, image_url }` - The type of the item. Always `tool_search_call`. + An image input to the model. Learn about [image inputs](/docs/guides/vision). - - `"tool_search_call"` + - `ResponseInputFile object { type, detail, file_data, 3 more }` - - `created_by: optional string` + A file input to the model. - The identifier of the actor that created the item. + - `type: "custom_tool_call_output"` - - `ToolSearchOutput object { id, call_id, execution, 4 more }` + The type of the custom tool call output. Always `custom_tool_call_output`. - - `id: string` + - `"custom_tool_call_output"` - The unique ID of the tool search output item. + - `id: optional string` - - `call_id: string` + The unique ID of the custom tool call output in the OpenAI platform. - The unique ID of the tool search call generated by the model. +### Example - - `execution: "server" or "client"` +```http +curl https://api.openai.com/v1/conversations/$CONVERSATION_ID/items/$ITEM_ID \ + -H "Authorization: Bearer $OPENAI_API_KEY" +``` - Whether tool search was executed by the server or by the client. +#### Response - - `"server"` +```json +{ + "id": "id", + "content": [ + { + "text": "text", + "type": "input_text" + } + ], + "role": "unknown", + "status": "in_progress", + "type": "message", + "phase": "commentary" +} +``` - - `"client"` +### Example - - `status: "in_progress" or "completed" or "incomplete"` +```http +curl https://api.openai.com/v1/conversations/conv_123/items/msg_abc \ + -H "Authorization: Bearer $OPENAI_API_KEY" +``` - The status of the tool search output item that was recorded. +#### Response - - `"in_progress"` +```json +{ + "type": "message", + "id": "msg_abc", + "status": "completed", + "role": "user", + "content": [ + {"type": "input_text", "text": "Hello!"} + ] +} +``` - - `"completed"` +## Delete an item - - `"incomplete"` +**delete** `/conversations/{conversation_id}/items/{item_id}` - - `tools: array of object { name, parameters, strict, 3 more } or object { type, vector_store_ids, filters, 2 more } or object { type } or 12 more` +Delete an item from a conversation with the given IDs. - The loaded tool definitions returned by tool search. +### Path Parameters - - `Function object { name, parameters, strict, 3 more }` +- `conversation_id: string` - 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). +- `item_id: string` - - `name: string` +### Returns - The name of the function to call. +- `Conversation object { id, created_at, metadata, object }` - - `parameters: map[unknown]` + - `id: string` - A JSON schema object describing the parameters of the function. + The unique ID of the conversation. - - `strict: boolean` + - `created_at: number` - Whether to enforce strict parameter validation. Default `true`. + The time at which the conversation was created, measured in seconds since the Unix epoch. - - `type: "function"` + - `metadata: unknown` - The type of the function tool. Always `function`. + Set of 16 key-value pairs that can be attached to an object. This can be useful for storing additional information about the object in a structured format, and querying for objects via API or the dashboard. + Keys are strings with a maximum length of 64 characters. Values are strings with a maximum length of 512 characters. - - `"function"` + - `object: "conversation"` - - `defer_loading: optional boolean` + The object type, which is always `conversation`. - Whether this function is deferred and loaded via tool search. + - `"conversation"` - - `description: optional string` +### Example - A description of the function. Used by the model to determine whether or not to call the function. +```http +curl https://api.openai.com/v1/conversations/$CONVERSATION_ID/items/$ITEM_ID \ + -X DELETE \ + -H "Authorization: Bearer $OPENAI_API_KEY" +``` - - `FileSearch object { type, vector_store_ids, filters, 2 more }` +#### Response - 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). +```json +{ + "id": "id", + "created_at": 0, + "metadata": {}, + "object": "conversation" +} +``` - - `type: "file_search"` +### Example - The type of the file search tool. Always `file_search`. +```http +curl -X DELETE https://api.openai.com/v1/conversations/conv_123/items/msg_abc \ + -H "Authorization: Bearer $OPENAI_API_KEY" +``` - - `"file_search"` +#### Response - - `vector_store_ids: array of string` +```json +{ + "id": "conv_123", + "object": "conversation", + "created_at": 1741900000, + "metadata": {"topic": "demo"} +} +``` - The IDs of the vector stores to search. +## Domain Types - - `filters: optional ComparisonFilter or CompoundFilter` +### Conversation Item - A filter to apply. +- `ConversationItem = Message or object { id, arguments, call_id, 5 more } or object { id, call_id, output, 3 more } or 23 more` - - `ComparisonFilter object { key, type, value }` + 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 filter used to compare a specified attribute key to a given value using a defined comparison operation. + - `Message object { id, content, role, 3 more }` - - `key: string` + A message to or from the model. - The key to compare against the value. + - `id: string` - - `type: "eq" or "ne" or "gt" or 5 more` + The unique ID of the message. - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + - `content: array of ResponseInputText or ResponseOutputText or TextContent or 6 more` - - `eq`: equals - - `ne`: not equal - - `gt`: greater than - - `gte`: greater than or equal - - `lt`: less than - - `lte`: less than or equal - - `in`: in - - `nin`: not in + The content of the message - - `"eq"` + - `ResponseInputText object { text, type }` - - `"ne"` + A text input to the model. - - `"gt"` + - `text: string` - - `"gte"` + The text input to the model. - - `"lt"` + - `type: "input_text"` - - `"lte"` + The type of the input item. Always `input_text`. - - `"in"` + - `"input_text"` - - `"nin"` + - `ResponseOutputText object { annotations, logprobs, text, type }` - - `value: string or number or boolean or array of string or number` + A text output from the model. - The value to compare against the attribute key; supports string, number, or boolean types. + - `annotations: array of object { file_id, filename, index, type } or object { end_index, start_index, title, 2 more } or object { container_id, end_index, file_id, 3 more } or object { file_id, index, type }` - - `string` + The annotations of the text output. - - `number` + - `FileCitation object { file_id, filename, index, type }` - - `boolean` + A citation to a file. - - `array of string or number` + - `file_id: string` - - `string` + The ID of the file. - - `number` + - `filename: string` - - `CompoundFilter object { filters, type }` + The filename of the file cited. - Combine multiple filters using `and` or `or`. + - `index: number` - - `filters: array of ComparisonFilter or unknown` + The index of the file in the list of files. - Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. + - `type: "file_citation"` - - `ComparisonFilter object { key, type, value }` + The type of the file citation. Always `file_citation`. - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + - `"file_citation"` - - `unknown` + - `URLCitation object { end_index, start_index, title, 2 more }` - - `type: "and" or "or"` + A citation for a web resource used to generate a model response. - Type of operation: `and` or `or`. + - `end_index: number` - - `"and"` + The index of the last character of the URL citation in the message. - - `"or"` + - `start_index: number` - - `max_num_results: optional number` + The index of the first character of the URL citation in the message. - The maximum number of results to return. This number should be between 1 and 50 inclusive. + - `title: string` - - `ranking_options: optional object { hybrid_search, ranker, score_threshold }` + The title of the web resource. - Ranking options for search. + - `type: "url_citation"` - - `hybrid_search: optional object { embedding_weight, text_weight }` + The type of the URL citation. Always `url_citation`. - Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. + - `"url_citation"` - - `embedding_weight: number` + - `url: string` - The weight of the embedding in the reciprocal ranking fusion. + The URL of the web resource. - - `text_weight: number` + - `ContainerFileCitation object { container_id, end_index, file_id, 3 more }` - The weight of the text in the reciprocal ranking fusion. + A citation for a container file used to generate a model response. - - `ranker: optional "auto" or "default-2024-11-15"` + - `container_id: string` - The ranker to use for the file search. + The ID of the container file. - - `"auto"` + - `end_index: number` - - `"default-2024-11-15"` + The index of the last character of the container file citation in the message. - - `score_threshold: optional number` + - `file_id: string` - The score threshold for the file search, a number between 0 and 1. Numbers closer to 1 will attempt to return only the most relevant results, but may return fewer results. + The ID of the file. - - `Computer object { type }` + - `filename: string` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + The filename of the container file cited. - - `type: "computer"` + - `start_index: number` - The type of the computer tool. Always `computer`. + The index of the first character of the container file citation in the message. - - `"computer"` + - `type: "container_file_citation"` - - `ComputerUsePreview object { display_height, display_width, environment, type }` + The type of the container file citation. Always `container_file_citation`. - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `"container_file_citation"` - - `display_height: number` + - `FilePath object { file_id, index, type }` - The height of the computer display. + A path to a file. - - `display_width: number` + - `file_id: string` - The width of the computer display. + The ID of the file. - - `environment: "windows" or "mac" or "linux" or 2 more` + - `index: number` - The type of computer environment to control. + The index of the file in the list of files. - - `"windows"` + - `type: "file_path"` - - `"mac"` + The type of the file path. Always `file_path`. - - `"linux"` + - `"file_path"` - - `"ubuntu"` + - `logprobs: array of object { token, bytes, logprob, top_logprobs }` - - `"browser"` + - `token: string` - - `type: "computer_use_preview"` + - `bytes: array of number` - The type of the computer use tool. Always `computer_use_preview`. + - `logprob: number` - - `"computer_use_preview"` + - `top_logprobs: array of object { token, bytes, logprob }` - - `WebSearch object { type, filters, search_context_size, user_location }` + - `token: string` - Search the Internet for sources related to the prompt. Learn more about the - [web search tool](/docs/guides/tools-web-search). + - `bytes: array of number` - - `type: "web_search" or "web_search_2025_08_26"` + - `logprob: number` - The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. + - `text: string` - - `"web_search"` + The text output from the model. - - `"web_search_2025_08_26"` + - `type: "output_text"` - - `filters: optional object { allowed_domains }` + The type of the output text. Always `output_text`. - Filters for the search. + - `"output_text"` - - `allowed_domains: optional array of string` + - `TextContent object { text, type }` - Allowed domains for the search. If not provided, all domains are allowed. - Subdomains of the provided domains are allowed as well. + A text content. - Example: `["pubmed.ncbi.nlm.nih.gov"]` + - `text: string` - - `search_context_size: optional "low" or "medium" or "high"` + - `type: "text"` - High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. + - `"text"` - - `"low"` + - `SummaryTextContent object { text, type }` - - `"medium"` + A summary text from the model. - - `"high"` + - `text: string` - - `user_location: optional object { city, country, region, 2 more }` + A summary of the reasoning output from the model so far. - The approximate location of the user. + - `type: "summary_text"` - - `city: optional string` + The type of the object. Always `summary_text`. - Free text input for the city of the user, e.g. `San Francisco`. + - `"summary_text"` - - `country: optional string` + - `ReasoningText object { text, type }` - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + Reasoning text from the model. - - `region: optional string` + - `text: string` - Free text input for the region of the user, e.g. `California`. + The reasoning text from the model. - - `timezone: optional string` + - `type: "reasoning_text"` - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + The type of the reasoning text. Always `reasoning_text`. - - `type: optional "approximate"` + - `"reasoning_text"` - The type of location approximation. Always `approximate`. + - `ResponseOutputRefusal object { refusal, type }` - - `"approximate"` + A refusal from the model. - - `Mcp object { server_label, type, allowed_tools, 7 more }` + - `refusal: string` - Give the model access to additional tools via remote Model Context Protocol - (MCP) servers. [Learn more about MCP](/docs/guides/tools-remote-mcp). + The refusal explanation from the model. - - `server_label: string` + - `type: "refusal"` - A label for this MCP server, used to identify it in tool calls. + The type of the refusal. Always `refusal`. - - `type: "mcp"` + - `"refusal"` - The type of the MCP tool. Always `mcp`. + - `ResponseInputImage object { detail, type, file_id, image_url }` - - `"mcp"` + An image input to the model. Learn about [image inputs](/docs/guides/vision). - - `allowed_tools: optional array of string or object { read_only, tool_names }` + - `detail: "low" or "high" or "auto" or "original"` - List of allowed tool names or a filter object. + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - - `McpAllowedTools = array of string` + - `"low"` - A string array of allowed tool names + - `"high"` - - `McpToolFilter object { read_only, tool_names }` + - `"auto"` - A filter object to specify which tools are allowed. + - `"original"` - - `read_only: optional boolean` + - `type: "input_image"` - Indicates whether or not a tool modifies data or is read-only. If an - MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), - it will match this filter. + The type of the input item. Always `input_image`. - - `tool_names: optional array of string` + - `"input_image"` - List of allowed tool names. + - `file_id: optional string` - - `authorization: optional string` + The ID of the file to be sent to the model. - An OAuth access token that can be used with a remote MCP server, either - with a custom MCP server URL or a service connector. Your application - must handle the OAuth authorization flow and provide the token here. + - `image_url: optional string` - - `connector_id: optional "connector_dropbox" or "connector_gmail" or "connector_googlecalendar" or 5 more` + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - Identifier for service connectors, like those available in ChatGPT. One of - `server_url` or `connector_id` must be provided. Learn more about service - connectors [here](/docs/guides/tools-remote-mcp#connectors). + - `ComputerScreenshotContent object { detail, file_id, image_url, type }` - Currently supported `connector_id` values are: + A screenshot of a computer. - - Dropbox: `connector_dropbox` - - Gmail: `connector_gmail` - - Google Calendar: `connector_googlecalendar` - - Google Drive: `connector_googledrive` - - Microsoft Teams: `connector_microsoftteams` - - Outlook Calendar: `connector_outlookcalendar` - - Outlook Email: `connector_outlookemail` - - SharePoint: `connector_sharepoint` + - `detail: "low" or "high" or "auto" or "original"` - - `"connector_dropbox"` + The detail level of the screenshot image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - - `"connector_gmail"` + - `"low"` - - `"connector_googlecalendar"` + - `"high"` - - `"connector_googledrive"` + - `"auto"` - - `"connector_microsoftteams"` + - `"original"` - - `"connector_outlookcalendar"` + - `file_id: string` - - `"connector_outlookemail"` + The identifier of an uploaded file that contains the screenshot. - - `"connector_sharepoint"` + - `image_url: string` - - `defer_loading: optional boolean` + The URL of the screenshot image. - Whether this MCP tool is deferred and discovered via tool search. + - `type: "computer_screenshot"` - - `headers: optional map[string]` + Specifies the event type. For a computer screenshot, this property is always set to `computer_screenshot`. - Optional HTTP headers to send to the MCP server. Use for authentication - or other purposes. + - `"computer_screenshot"` - - `require_approval: optional object { always, never } or "always" or "never"` + - `ResponseInputFile object { type, detail, file_data, 3 more }` - Specify which of the MCP server's tools require approval. + A file input to the model. - - `McpToolApprovalFilter object { always, never }` + - `type: "input_file"` - Specify which of the MCP server's tools require approval. Can be - `always`, `never`, or a filter object associated with tools - that require approval. + The type of the input item. Always `input_file`. - - `always: optional object { read_only, tool_names }` + - `"input_file"` - A filter object to specify which tools are allowed. + - `detail: optional "low" or "high"` - - `read_only: optional boolean` + 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`. - Indicates whether or not a tool modifies data or is read-only. If an - MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), - it will match this filter. + - `"low"` - - `tool_names: optional array of string` + - `"high"` - List of allowed tool names. + - `file_data: optional string` - - `never: optional object { read_only, tool_names }` + The content of the file to be sent to the model. - A filter object to specify which tools are allowed. + - `file_id: optional string` - - `read_only: optional boolean` + The ID of the file to be sent to the model. - Indicates whether or not a tool modifies data or is read-only. If an - MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), - it will match this filter. + - `file_url: optional string` - - `tool_names: optional array of string` + The URL of the file to be sent to the model. - List of allowed tool names. + - `filename: optional string` - - `McpToolApprovalSetting = "always" or "never"` + The name of the file to be sent to the model. - Specify a single approval policy for all tools. One of `always` or - `never`. When set to `always`, all tools will require approval. When - set to `never`, all tools will not require approval. + - `role: "unknown" or "user" or "assistant" or 5 more` - - `"always"` + The role of the message. One of `unknown`, `user`, `assistant`, `system`, `critic`, `discriminator`, `developer`, or `tool`. - - `"never"` + - `"unknown"` - - `server_description: optional string` + - `"user"` - Optional description of the MCP server, used to provide more context. + - `"assistant"` - - `server_url: optional string` + - `"system"` - The URL for the MCP server. One of `server_url` or `connector_id` must be - provided. + - `"critic"` - - `CodeInterpreter object { container, type }` + - `"discriminator"` - A tool that runs Python code to help generate a response to a prompt. + - `"developer"` - - `container: string or object { type, file_ids, memory_limit, network_policy }` + - `"tool"` - The code interpreter container. Can be a container ID or an object that - specifies uploaded file IDs to make available to your code, along with an - optional `memory_limit` setting. + - `status: "in_progress" or "completed" or "incomplete"` - - `string` + The status of item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. - The container ID. + - `"in_progress"` - - `CodeInterpreterToolAuto object { type, file_ids, memory_limit, network_policy }` + - `"completed"` - Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. + - `"incomplete"` - - `type: "auto"` + - `type: "message"` - Always `auto`. + The type of the message. Always set to `message`. - - `"auto"` + - `"message"` - - `file_ids: optional array of string` + - `phase: optional "commentary" or "final_answer"` - An optional list of uploaded files to make available to your code. + Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend phase on all assistant messages — dropping it can degrade performance. Not used for user messages. - - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` + - `"commentary"` - The memory limit for the code interpreter container. + - `"final_answer"` - - `"1g"` + - `FunctionCall object { id, arguments, call_id, 5 more }` - - `"4g"` + - `id: string` - - `"16g"` + The unique ID of the function tool call. - - `"64g"` + - `arguments: string` - - `network_policy: optional ContainerNetworkPolicyDisabled or ContainerNetworkPolicyAllowlist` + A JSON string of the arguments to pass to the function. - Network access policy for the container. + - `call_id: string` - - `ContainerNetworkPolicyDisabled object { type }` + The unique ID of the function tool call generated by the model. - - `type: "disabled"` + - `name: string` - Disable outbound network access. Always `disabled`. + The name of the function to run. - - `"disabled"` + - `status: "in_progress" or "completed" or "incomplete"` - - `ContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `allowed_domains: array of string` + - `"in_progress"` - A list of allowed domains when type is `allowlist`. + - `"completed"` - - `type: "allowlist"` + - `"incomplete"` - Allow outbound network access only to specified domains. Always `allowlist`. + - `type: "function_call"` - - `"allowlist"` + The type of the function tool call. Always `function_call`. - - `domain_secrets: optional array of ContainerNetworkPolicyDomainSecret` + - `"function_call"` - Optional domain-scoped secrets for allowlisted domains. + - `created_by: optional string` - - `domain: string` + The identifier of the actor that created the item. - The domain associated with the secret. + - `namespace: optional string` - - `name: string` + The namespace of the function to run. - The name of the secret to inject for the domain. + - `FunctionCallOutput object { id, call_id, output, 3 more }` - - `value: string` + - `id: string` - The secret value to inject for the domain. + The unique ID of the function call tool output. - - `type: "code_interpreter"` + - `call_id: string` - The type of the code interpreter tool. Always `code_interpreter`. + The unique ID of the function tool call generated by the model. - - `"code_interpreter"` + - `output: string or array of ResponseInputText or ResponseInputImage or ResponseInputFile` - - `ImageGeneration object { type, action, background, 9 more }` + The output from the function call generated by your code. + Can be a string or an list of output content. - A tool that generates images using the GPT image models. + - `StringOutput = string` - - `type: "image_generation"` + A string of the output of the function call. - The type of the image generation tool. Always `image_generation`. + - `OutputContentList = array of ResponseInputText or ResponseInputImage or ResponseInputFile` - - `"image_generation"` + Text, image, or file output of the function call. - - `action: optional "generate" or "edit" or "auto"` + - `ResponseInputText object { text, type }` - Whether to generate a new image or edit an existing image. Default: `auto`. + A text input to the model. - - `"generate"` + - `ResponseInputImage object { detail, type, file_id, image_url }` - - `"edit"` + An image input to the model. Learn about [image inputs](/docs/guides/vision). - - `"auto"` + - `ResponseInputFile object { type, detail, file_data, 3 more }` - - `background: optional "transparent" or "opaque" or "auto"` + A file input to the model. - Background type for the generated image. One of `transparent`, - `opaque`, or `auto`. Default: `auto`. + - `status: "in_progress" or "completed" or "incomplete"` - - `"transparent"` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `"opaque"` + - `"in_progress"` - - `"auto"` + - `"completed"` - - `input_fidelity: optional "high" or "low"` + - `"incomplete"` - Control how much effort the model will exert to match the style and features, especially facial features, of input images. This parameter is only supported for `gpt-image-1` and `gpt-image-1.5` and later models, unsupported for `gpt-image-1-mini`. Supports `high` and `low`. Defaults to `low`. + - `type: "function_call_output"` - - `"high"` + The type of the function tool call output. Always `function_call_output`. - - `"low"` + - `"function_call_output"` - - `input_image_mask: optional object { file_id, image_url }` + - `created_by: optional string` - Optional mask for inpainting. Contains `image_url` - (string, optional) and `file_id` (string, optional). + The identifier of the actor that created the item. - - `file_id: optional string` + - `FileSearchCall object { id, queries, status, 2 more }` - File ID for the mask image. + The results of a file search tool call. See the + [file search guide](/docs/guides/tools-file-search) for more information. - - `image_url: optional string` + - `id: string` - Base64-encoded mask image. + The unique ID of the file search tool call. - - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` + - `queries: array of string` - The image generation model to use. Default: `gpt-image-1`. + The queries used to search for files. - - `string` + - `status: "in_progress" or "searching" or "completed" or 2 more` - - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` + The status of the file search tool call. One of `in_progress`, + `searching`, `incomplete` or `failed`, - The image generation model to use. Default: `gpt-image-1`. + - `"in_progress"` - - `"gpt-image-1"` + - `"searching"` - - `"gpt-image-1-mini"` + - `"completed"` - - `"gpt-image-1.5"` + - `"incomplete"` - - `moderation: optional "auto" or "low"` + - `"failed"` - Moderation level for the generated image. Default: `auto`. + - `type: "file_search_call"` - - `"auto"` + The type of the file search tool call. Always `file_search_call`. - - `"low"` + - `"file_search_call"` - - `output_compression: optional number` + - `results: optional array of object { attributes, file_id, filename, 2 more }` - Compression level for the output image. Default: 100. + The results of the file search tool call. - - `output_format: optional "png" or "webp" or "jpeg"` + - `attributes: optional map[string or number or boolean]` - The output format of the generated image. One of `png`, `webp`, or - `jpeg`. Default: `png`. + Set of 16 key-value pairs that can be attached to an object. This can be + useful for storing additional information about the object in a structured + format, and querying for objects via API or the dashboard. Keys are strings + with a maximum length of 64 characters. Values are strings with a maximum + length of 512 characters, booleans, or numbers. - - `"png"` + - `string` - - `"webp"` + - `number` - - `"jpeg"` + - `boolean` - - `partial_images: optional number` + - `file_id: optional string` - Number of partial images to generate in streaming mode, from 0 (default value) to 3. + The unique ID of the file. - - `quality: optional "low" or "medium" or "high" or "auto"` + - `filename: optional string` - The quality of the generated image. One of `low`, `medium`, `high`, - or `auto`. Default: `auto`. + The name of the file. - - `"low"` + - `score: optional number` - - `"medium"` + The relevance score of the file - a value between 0 and 1. - - `"high"` + - `text: optional string` - - `"auto"` + The text that was retrieved from the file. - - `size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or "auto"` + - `WebSearchCall object { id, action, status, type }` - The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. + The results of a web search tool call. See the + [web search guide](/docs/guides/tools-web-search) for more information. - - `string` + - `id: string` - - `"1024x1024" or "1024x1536" or "1536x1024" or "auto"` + The unique ID of the web search tool call. - The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. + - `action: object { type, queries, query, sources } or object { type, url } or object { pattern, type, url }` - - `"1024x1024"` + An object describing the specific action taken in this web search call. + Includes details on how the model used the web (search, open_page, find_in_page). - - `"1024x1536"` + - `Search object { type, queries, query, sources }` - - `"1536x1024"` + Action type "search" - Performs a web search query. - - `"auto"` + - `type: "search"` - - `LocalShell object { type }` + The action type. - A tool that allows the model to execute shell commands in a local environment. + - `"search"` - - `type: "local_shell"` + - `queries: optional array of string` - The type of the local shell tool. Always `local_shell`. + The search queries. - - `"local_shell"` + - `query: optional string` - - `Shell object { type, environment }` + The search query. - A tool that allows the model to execute shell commands. + - `sources: optional array of object { type, url }` - - `type: "shell"` + The sources used in the search. - The type of the shell tool. Always `shell`. + - `type: "url"` - - `"shell"` + The type of source. Always `url`. - - `environment: optional ContainerAuto or LocalEnvironment or ContainerReference` + - `"url"` - - `ContainerAuto object { type, file_ids, memory_limit, 2 more }` + - `url: string` - - `type: "container_auto"` + The URL of the source. - Automatically creates a container for this request + - `OpenPage object { type, url }` - - `"container_auto"` + Action type "open_page" - Opens a specific URL from search results. - - `file_ids: optional array of string` + - `type: "open_page"` - An optional list of uploaded files to make available to your code. + The action type. - - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` + - `"open_page"` - The memory limit for the container. + - `url: optional string` - - `"1g"` + The URL opened by the model. - - `"4g"` + - `FindInPage object { pattern, type, url }` - - `"16g"` + Action type "find_in_page": Searches for a pattern within a loaded page. - - `"64g"` + - `pattern: string` - - `network_policy: optional ContainerNetworkPolicyDisabled or ContainerNetworkPolicyAllowlist` + The pattern or text to search for within the page. - Network access policy for the container. + - `type: "find_in_page"` - - `ContainerNetworkPolicyDisabled object { type }` + The action type. - - `ContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` + - `"find_in_page"` - - `skills: optional array of SkillReference or InlineSkill` + - `url: string` - An optional list of skills referenced by id or inline data. + The URL of the page searched for the pattern. - - `SkillReference object { skill_id, type, version }` + - `status: "in_progress" or "searching" or "completed" or "failed"` - - `skill_id: string` + The status of the web search tool call. - The ID of the referenced skill. + - `"in_progress"` - - `type: "skill_reference"` + - `"searching"` - References a skill created with the /v1/skills endpoint. + - `"completed"` - - `"skill_reference"` + - `"failed"` - - `version: optional string` + - `type: "web_search_call"` - Optional skill version. Use a positive integer or 'latest'. Omit for default. + The type of the web search tool call. Always `web_search_call`. - - `InlineSkill object { description, name, source, type }` + - `"web_search_call"` - - `description: string` + - `ImageGenerationCall object { id, result, status, type }` - The description of the skill. + An image generation request made by the model. - - `name: string` + - `id: string` - The name of the skill. + The unique ID of the image generation call. - - `source: InlineSkillSource` + - `result: string` - Inline skill payload + The generated image encoded in base64. - - `data: string` + - `status: "in_progress" or "completed" or "generating" or "failed"` - Base64-encoded skill zip bundle. + The status of the image generation call. - - `media_type: "application/zip"` + - `"in_progress"` - The media type of the inline skill payload. Must be `application/zip`. + - `"completed"` - - `"application/zip"` + - `"generating"` - - `type: "base64"` + - `"failed"` - The type of the inline skill source. Must be `base64`. + - `type: "image_generation_call"` - - `"base64"` + The type of the image generation call. Always `image_generation_call`. - - `type: "inline"` + - `"image_generation_call"` - Defines an inline skill for this request. + - `ComputerCall object { id, call_id, pending_safety_checks, 4 more }` - - `"inline"` + A tool call to a computer use tool. See the + [computer use guide](/docs/guides/tools-computer-use) for more information. - - `LocalEnvironment object { type, skills }` + - `id: string` - - `type: "local"` + The unique ID of the computer call. - Use a local computer environment. + - `call_id: string` - - `"local"` + An identifier used when responding to the tool call with output. - - `skills: optional array of LocalSkill` + - `pending_safety_checks: array of object { id, code, message }` - An optional list of skills. + The pending safety checks for the computer call. - - `description: string` + - `id: string` - The description of the skill. + The ID of the pending safety check. - - `name: string` + - `code: optional string` - The name of the skill. + The type of the pending safety check. - - `path: string` + - `message: optional string` - The path to the directory containing the skill. + Details about the pending safety check. - - `ContainerReference object { container_id, type }` + - `status: "in_progress" or "completed" or "incomplete"` - - `container_id: string` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - The ID of the referenced container. + - `"in_progress"` - - `type: "container_reference"` + - `"completed"` - References a container created with the /v1/containers endpoint + - `"incomplete"` - - `"container_reference"` + - `type: "computer_call"` - - `Custom object { name, type, defer_loading, 2 more }` + The type of the computer call. Always `computer_call`. - A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) + - `"computer_call"` - - `name: string` + - `action: optional ComputerAction` - The name of the custom tool, used to identify it in tool calls. + A click action. - - `type: "custom"` + - `Click object { button, type, x, 2 more }` - The type of the custom tool. Always `custom`. + A click action. - - `"custom"` + - `button: "left" or "right" or "wheel" or 2 more` - - `defer_loading: optional boolean` + Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. - Whether this tool should be deferred and discovered via tool search. + - `"left"` - - `description: optional string` + - `"right"` - Optional description of the custom tool, used to provide more context. + - `"wheel"` - - `format: optional CustomToolInputFormat` + - `"back"` - The input format for the custom tool. Default is unconstrained text. + - `"forward"` - - `Text object { type }` + - `type: "click"` - Unconstrained free-form text. + Specifies the event type. For a click action, this property is always `click`. - - `type: "text"` + - `"click"` - Unconstrained text format. Always `text`. + - `x: number` - - `"text"` + The x-coordinate where the click occurred. - - `Grammar object { definition, syntax, type }` + - `y: number` - A grammar defined by the user. + The y-coordinate where the click occurred. - - `definition: string` + - `keys: optional array of string` - The grammar definition. + The keys being held while clicking. - - `syntax: "lark" or "regex"` + - `DoubleClick object { keys, type, x, y }` - The syntax of the grammar definition. One of `lark` or `regex`. + A double click action. - - `"lark"` + - `keys: array of string` - - `"regex"` + The keys being held while double-clicking. - - `type: "grammar"` + - `type: "double_click"` - Grammar format. Always `grammar`. + Specifies the event type. For a double click action, this property is always set to `double_click`. - - `"grammar"` + - `"double_click"` - - `Namespace object { description, name, tools, type }` + - `x: number` - Groups function/custom tools under a shared namespace. + The x-coordinate where the double click occurred. - - `description: string` + - `y: number` - A description of the namespace shown to the model. + The y-coordinate where the double click occurred. - - `name: string` + - `Drag object { path, type, keys }` - The namespace name used in tool calls (for example, `crm`). + A drag action. - - `tools: array of object { name, type, defer_loading, 3 more } or object { name, type, defer_loading, 2 more }` + - `path: array of object { x, y }` - The function/custom tools available inside this namespace. + An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg - - `Function object { name, type, defer_loading, 3 more }` + ``` + [ + { x: 100, y: 200 }, + { x: 200, y: 300 } + ] + ``` - - `name: string` + - `x: number` - - `type: "function"` + The x-coordinate. - - `"function"` + - `y: number` - - `defer_loading: optional boolean` + The y-coordinate. - Whether this function should be deferred and discovered via tool search. + - `type: "drag"` - - `description: optional string` + Specifies the event type. For a drag action, this property is always set to `drag`. - - `parameters: optional unknown` + - `"drag"` - - `strict: optional boolean` + - `keys: optional array of string` - - `Custom object { name, type, defer_loading, 2 more }` + The keys being held while dragging the mouse. - A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) + - `Keypress object { keys, type }` - - `name: string` + A collection of keypresses the model would like to perform. - The name of the custom tool, used to identify it in tool calls. + - `keys: array of string` - - `type: "custom"` + The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. - The type of the custom tool. Always `custom`. + - `type: "keypress"` - - `"custom"` + Specifies the event type. For a keypress action, this property is always set to `keypress`. - - `defer_loading: optional boolean` + - `"keypress"` - Whether this tool should be deferred and discovered via tool search. + - `Move object { type, x, y, keys }` - - `description: optional string` + A mouse move action. - Optional description of the custom tool, used to provide more context. + - `type: "move"` - - `format: optional CustomToolInputFormat` + Specifies the event type. For a move action, this property is always set to `move`. - The input format for the custom tool. Default is unconstrained text. + - `"move"` - - `type: "namespace"` + - `x: number` - The type of the tool. Always `namespace`. + The x-coordinate to move to. - - `"namespace"` + - `y: number` - - `ToolSearch object { type, description, execution, parameters }` + The y-coordinate to move to. - Hosted or BYOT tool search configuration for deferred tools. + - `keys: optional array of string` - - `type: "tool_search"` + The keys being held while moving the mouse. - The type of the tool. Always `tool_search`. + - `Screenshot object { type }` - - `"tool_search"` + A screenshot action. - - `description: optional string` + - `type: "screenshot"` - Description shown to the model for a client-executed tool search tool. + Specifies the event type. For a screenshot action, this property is always set to `screenshot`. - - `execution: optional "server" or "client"` + - `"screenshot"` - Whether tool search is executed by the server or by the client. + - `Scroll object { scroll_x, scroll_y, type, 3 more }` - - `"server"` + A scroll action. - - `"client"` + - `scroll_x: number` - - `parameters: optional unknown` + The horizontal scroll distance. - Parameter schema for a client-executed tool search tool. + - `scroll_y: number` - - `WebSearchPreview object { type, search_content_types, search_context_size, user_location }` + The vertical scroll distance. - This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + - `type: "scroll"` - - `type: "web_search_preview" or "web_search_preview_2025_03_11"` + Specifies the event type. For a scroll action, this property is always set to `scroll`. - The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. + - `"scroll"` - - `"web_search_preview"` + - `x: number` - - `"web_search_preview_2025_03_11"` + The x-coordinate where the scroll occurred. - - `search_content_types: optional array of "text" or "image"` + - `y: number` - - `"text"` + The y-coordinate where the scroll occurred. - - `"image"` + - `keys: optional array of string` - - `search_context_size: optional "low" or "medium" or "high"` + The keys being held while scrolling. - High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. + - `Type object { text, type }` - - `"low"` + An action to type in text. - - `"medium"` + - `text: string` - - `"high"` + The text to type. - - `user_location: optional object { type, city, country, 2 more }` + - `type: "type"` - The user's location. + Specifies the event type. For a type action, this property is always set to `type`. - - `type: "approximate"` + - `"type"` - The type of location approximation. Always `approximate`. + - `Wait object { type }` - - `"approximate"` + A wait action. - - `city: optional string` + - `type: "wait"` - Free text input for the city of the user, e.g. `San Francisco`. + Specifies the event type. For a wait action, this property is always set to `wait`. - - `country: optional string` + - `"wait"` - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + - `actions: optional ComputerActionList` - - `region: optional string` + Flattened batched actions for `computer_use`. Each action includes an + `type` discriminator and action-specific fields. - Free text input for the region of the user, e.g. `California`. + - `Click object { button, type, x, 2 more }` - - `timezone: optional string` + A click action. - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + - `DoubleClick object { keys, type, x, y }` - - `ApplyPatch object { type }` + A double click action. - Allows the assistant to create, delete, or update files using unified diffs. + - `Drag object { path, type, keys }` - - `type: "apply_patch"` + A drag action. - The type of the tool. Always `apply_patch`. + - `Keypress object { keys, type }` - - `"apply_patch"` + A collection of keypresses the model would like to perform. - - `type: "tool_search_output"` + - `Move object { type, x, y, keys }` - The type of the item. Always `tool_search_output`. + A mouse move action. - - `"tool_search_output"` + - `Screenshot object { type }` - - `created_by: optional string` + A screenshot action. - The identifier of the actor that created the item. + - `Scroll object { scroll_x, scroll_y, type, 3 more }` - - `Reasoning object { id, summary, type, 3 more }` + A scroll action. - 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). + - `Type object { text, type }` - - `id: string` + An action to type in text. - The unique identifier of the reasoning content. + - `Wait object { type }` - - `summary: array of SummaryTextContent` + A wait action. - Reasoning summary content. + - `ComputerCallOutput object { id, call_id, output, 4 more }` - - `text: string` + - `id: string` - A summary of the reasoning output from the model so far. + The unique ID of the computer call tool output. - - `type: "summary_text"` + - `call_id: string` - The type of the object. Always `summary_text`. + The ID of the computer tool call that produced the output. - - `type: "reasoning"` + - `output: ResponseComputerToolCallOutputScreenshot` - The type of the object. Always `reasoning`. + A computer screenshot image used with the computer use tool. - - `"reasoning"` + - `type: "computer_screenshot"` - - `content: optional array of object { text, type }` + Specifies the event type. For a computer screenshot, this property is + always set to `computer_screenshot`. - Reasoning text content. + - `"computer_screenshot"` - - `text: string` + - `file_id: optional string` - The reasoning text from the model. + The identifier of an uploaded file that contains the screenshot. - - `type: "reasoning_text"` + - `image_url: optional string` - The type of the reasoning text. Always `reasoning_text`. + The URL of the screenshot image. - - `"reasoning_text"` + - `status: "completed" or "incomplete" or "failed" or "in_progress"` - - `encrypted_content: optional string` + The status of the message input. One of `in_progress`, `completed`, or + `incomplete`. Populated when input items are returned via API. - The encrypted content of the reasoning item - populated when a response is - generated with `reasoning.encrypted_content` in the `include` parameter. + - `"completed"` - - `status: optional "in_progress" or "completed" or "incomplete"` + - `"incomplete"` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `"failed"` - `"in_progress"` - - `"completed"` + - `type: "computer_call_output"` - - `"incomplete"` + The type of the computer tool call output. Always `computer_call_output`. - - `Compaction object { id, encrypted_content, type, created_by }` + - `"computer_call_output"` - A compaction item generated by the [`v1/responses/compact` API](/docs/api-reference/responses/compact). + - `acknowledged_safety_checks: optional array of object { id, code, message }` - - `id: string` + The safety checks reported by the API that have been acknowledged by the + developer. - The unique ID of the compaction item. + - `id: string` - - `encrypted_content: string` + The ID of the pending safety check. - The encrypted content that was produced by compaction. + - `code: optional string` - - `type: "compaction"` + The type of the pending safety check. - The type of the item. Always `compaction`. + - `message: optional string` - - `"compaction"` + Details about the pending safety check. - `created_by: optional string` The identifier of the actor that created the item. - - `CodeInterpreterCall object { id, code, container_id, 3 more }` - - A tool call to run code. + - `ToolSearchCall object { id, arguments, call_id, 4 more }` - `id: string` - The unique ID of the code interpreter tool call. + The unique ID of the tool search call item. - - `code: string` + - `arguments: unknown` - The code to run, or null if not available. + Arguments used for the tool search call. - - `container_id: string` + - `call_id: string` - The ID of the container used to run the code. + The unique ID of the tool search call generated by the model. - - `outputs: array of object { logs, type } or object { type, url }` + - `execution: "server" or "client"` - The outputs generated by the code interpreter, such as logs or images. - Can be null if no outputs are available. + Whether tool search was executed by the server or by the client. - - `Logs object { logs, type }` + - `"server"` - The logs output from the code interpreter. + - `"client"` - - `logs: string` + - `status: "in_progress" or "completed" or "incomplete"` - The logs output from the code interpreter. + The status of the tool search call item that was recorded. - - `type: "logs"` + - `"in_progress"` - The type of the output. Always `logs`. + - `"completed"` - - `"logs"` + - `"incomplete"` - - `Image object { type, url }` + - `type: "tool_search_call"` - The image output from the code interpreter. + The type of the item. Always `tool_search_call`. - - `type: "image"` + - `"tool_search_call"` - The type of the output. Always `image`. + - `created_by: optional string` - - `"image"` + The identifier of the actor that created the item. - - `url: string` + - `ToolSearchOutput object { id, call_id, execution, 4 more }` - The URL of the image output from the code interpreter. + - `id: string` - - `status: "in_progress" or "completed" or "incomplete" or 2 more` + The unique ID of the tool search output item. - The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. + - `call_id: string` - - `"in_progress"` + The unique ID of the tool search call generated by the model. - - `"completed"` + - `execution: "server" or "client"` - - `"incomplete"` + Whether tool search was executed by the server or by the client. - - `"interpreting"` + - `"server"` - - `"failed"` + - `"client"` - - `type: "code_interpreter_call"` + - `status: "in_progress" or "completed" or "incomplete"` - The type of the code interpreter tool call. Always `code_interpreter_call`. + The status of the tool search output item that was recorded. - - `"code_interpreter_call"` + - `"in_progress"` - - `LocalShellCall object { id, action, call_id, 2 more }` + - `"completed"` - A tool call to run a command on the local shell. + - `"incomplete"` - - `id: string` + - `tools: array of object { name, parameters, strict, 3 more } or object { type, vector_store_ids, filters, 2 more } or object { type } or 12 more` - The unique ID of the local shell call. + The loaded tool definitions returned by tool search. - - `action: object { command, env, type, 3 more }` + - `Function object { name, parameters, strict, 3 more }` - Execute a shell command on the server. + 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). - - `command: array of string` + - `name: string` - The command to run. + The name of the function to call. - - `env: map[string]` + - `parameters: map[unknown]` - Environment variables to set for the command. + A JSON schema object describing the parameters of the function. + + - `strict: boolean` + + Whether to enforce strict parameter validation. Default `true`. - - `type: "exec"` + - `type: "function"` - The type of the local shell action. Always `exec`. + The type of the function tool. Always `function`. - - `"exec"` + - `"function"` - - `timeout_ms: optional number` + - `defer_loading: optional boolean` - Optional timeout in milliseconds for the command. + Whether this function is deferred and loaded via tool search. - - `user: optional string` + - `description: optional string` - Optional user to run the command as. + A description of the function. Used by the model to determine whether or not to call the function. - - `working_directory: optional string` + - `FileSearch object { type, vector_store_ids, filters, 2 more }` - Optional working directory to run the command in. + 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). - - `call_id: string` + - `type: "file_search"` - The unique ID of the local shell tool call generated by the model. + The type of the file search tool. Always `file_search`. - - `status: "in_progress" or "completed" or "incomplete"` + - `"file_search"` - The status of the local shell call. + - `vector_store_ids: array of string` - - `"in_progress"` + The IDs of the vector stores to search. - - `"completed"` + - `filters: optional ComparisonFilter or CompoundFilter` - - `"incomplete"` + A filter to apply. - - `type: "local_shell_call"` + - `ComparisonFilter object { key, type, value }` - The type of the local shell call. Always `local_shell_call`. + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - - `"local_shell_call"` + - `key: string` - - `LocalShellCallOutput object { id, output, type, status }` + The key to compare against the value. - The output of a local shell tool call. + - `type: "eq" or "ne" or "gt" or 5 more` - - `id: string` + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - The unique ID of the local shell tool call generated by the model. + - `eq`: equals + - `ne`: not equal + - `gt`: greater than + - `gte`: greater than or equal + - `lt`: less than + - `lte`: less than or equal + - `in`: in + - `nin`: not in - - `output: string` + - `"eq"` - A JSON string of the output of the local shell tool call. + - `"ne"` - - `type: "local_shell_call_output"` + - `"gt"` - The type of the local shell tool call output. Always `local_shell_call_output`. + - `"gte"` - - `"local_shell_call_output"` + - `"lt"` - - `status: optional "in_progress" or "completed" or "incomplete"` + - `"lte"` - The status of the item. One of `in_progress`, `completed`, or `incomplete`. + - `"in"` - - `"in_progress"` + - `"nin"` - - `"completed"` + - `value: string or number or boolean or array of string or number` - - `"incomplete"` + The value to compare against the attribute key; supports string, number, or boolean types. - - `ShellCall object { id, action, call_id, 4 more }` + - `string` - A tool call that executes one or more shell commands in a managed environment. + - `number` - - `id: string` + - `boolean` - The unique ID of the shell tool call. Populated when this item is returned via API. + - `array of string or number` - - `action: object { commands, max_output_length, timeout_ms }` + - `string` - The shell commands and limits that describe how to run the tool call. + - `number` - - `commands: array of string` + - `CompoundFilter object { filters, type }` - - `max_output_length: number` + Combine multiple filters using `and` or `or`. - Optional maximum number of characters to return from each command. + - `filters: array of ComparisonFilter or unknown` - - `timeout_ms: number` + Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. - Optional timeout in milliseconds for the commands. + - `ComparisonFilter object { key, type, value }` - - `call_id: string` + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - The unique ID of the shell tool call generated by the model. + - `unknown` - - `environment: ResponseLocalEnvironment or ResponseContainerReference` + - `type: "and" or "or"` - Represents the use of a local environment to perform shell actions. + Type of operation: `and` or `or`. - - `ResponseLocalEnvironment object { type }` + - `"and"` - Represents the use of a local environment to perform shell actions. + - `"or"` - - `type: "local"` + - `max_num_results: optional number` - The environment type. Always `local`. + The maximum number of results to return. This number should be between 1 and 50 inclusive. - - `"local"` + - `ranking_options: optional object { hybrid_search, ranker, score_threshold }` - - `ResponseContainerReference object { container_id, type }` + Ranking options for search. - Represents a container created with /v1/containers. + - `hybrid_search: optional object { embedding_weight, text_weight }` - - `container_id: string` + Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. - - `type: "container_reference"` + - `embedding_weight: number` - The environment type. Always `container_reference`. + The weight of the embedding in the reciprocal ranking fusion. - - `"container_reference"` + - `text_weight: number` - - `status: "in_progress" or "completed" or "incomplete"` + The weight of the text in the reciprocal ranking fusion. - The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. + - `ranker: optional "auto" or "default-2024-11-15"` - - `"in_progress"` + The ranker to use for the file search. - - `"completed"` + - `"auto"` - - `"incomplete"` + - `"default-2024-11-15"` - - `type: "shell_call"` + - `score_threshold: optional number` - The type of the item. Always `shell_call`. + The score threshold for the file search, a number between 0 and 1. Numbers closer to 1 will attempt to return only the most relevant results, but may return fewer results. - - `"shell_call"` + - `Computer object { type }` - - `created_by: optional string` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - The ID of the entity that created this tool call. + - `type: "computer"` - - `ShellCallOutput object { id, call_id, max_output_length, 4 more }` + The type of the computer tool. Always `computer`. - The output of a shell tool call that was emitted. + - `"computer"` - - `id: string` + - `ComputerUsePreview object { display_height, display_width, environment, type }` - The unique ID of the shell call output. Populated when this item is returned via API. + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `call_id: string` + - `display_height: number` - The unique ID of the shell tool call generated by the model. + The height of the computer display. - - `max_output_length: number` + - `display_width: number` - The maximum length of the shell command output. This is generated by the model and should be passed back with the raw output. + The width of the computer display. - - `output: array of object { outcome, stderr, stdout, created_by }` + - `environment: "windows" or "mac" or "linux" or 2 more` - An array of shell call output contents + The type of computer environment to control. - - `outcome: object { type } or object { exit_code, type }` + - `"windows"` - Represents either an exit outcome (with an exit code) or a timeout outcome for a shell call output chunk. + - `"mac"` - - `Timeout object { type }` + - `"linux"` - Indicates that the shell call exceeded its configured time limit. + - `"ubuntu"` - - `type: "timeout"` + - `"browser"` - The outcome type. Always `timeout`. + - `type: "computer_use_preview"` - - `"timeout"` + The type of the computer use tool. Always `computer_use_preview`. - - `Exit object { exit_code, type }` + - `"computer_use_preview"` - Indicates that the shell commands finished and returned an exit code. + - `WebSearch object { type, filters, search_context_size, user_location }` - - `exit_code: number` + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](/docs/guides/tools-web-search). - Exit code from the shell process. + - `type: "web_search" or "web_search_2025_08_26"` - - `type: "exit"` + The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. - The outcome type. Always `exit`. + - `"web_search"` - - `"exit"` + - `"web_search_2025_08_26"` - - `stderr: string` + - `filters: optional object { allowed_domains }` - The standard error output that was captured. + Filters for the search. - - `stdout: string` + - `allowed_domains: optional array of string` - The standard output that was captured. + Allowed domains for the search. If not provided, all domains are allowed. + Subdomains of the provided domains are allowed as well. - - `created_by: optional string` + Example: `["pubmed.ncbi.nlm.nih.gov"]` - The identifier of the actor that created the item. + - `search_context_size: optional "low" or "medium" or "high"` - - `status: "in_progress" or "completed" or "incomplete"` + High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. - The status of the shell call output. One of `in_progress`, `completed`, or `incomplete`. + - `"low"` - - `"in_progress"` + - `"medium"` - - `"completed"` + - `"high"` - - `"incomplete"` + - `user_location: optional object { city, country, region, 2 more }` - - `type: "shell_call_output"` + The approximate location of the user. - The type of the shell call output. Always `shell_call_output`. + - `city: optional string` - - `"shell_call_output"` + Free text input for the city of the user, e.g. `San Francisco`. - - `created_by: optional string` + - `country: optional string` - The identifier of the actor that created the item. + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - - `ApplyPatchCall object { id, call_id, operation, 3 more }` + - `region: optional string` - A tool call that applies file diffs by creating, deleting, or updating files. + Free text input for the region of the user, e.g. `California`. - - `id: string` + - `timezone: optional string` - The unique ID of the apply patch tool call. Populated when this item is returned via API. + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - - `call_id: string` + - `type: optional "approximate"` - The unique ID of the apply patch tool call generated by the model. + The type of location approximation. Always `approximate`. - - `operation: object { diff, path, type } or object { path, type } or object { diff, path, type }` + - `"approximate"` - One of the create_file, delete_file, or update_file operations applied via apply_patch. + - `Mcp object { server_label, type, allowed_tools, 7 more }` - - `CreateFile object { diff, path, type }` + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](/docs/guides/tools-remote-mcp). - Instruction describing how to create a file via the apply_patch tool. + - `server_label: string` - - `diff: string` + A label for this MCP server, used to identify it in tool calls. - Diff to apply. + - `type: "mcp"` - - `path: string` + The type of the MCP tool. Always `mcp`. - Path of the file to create. + - `"mcp"` - - `type: "create_file"` + - `allowed_tools: optional array of string or object { read_only, tool_names }` - Create a new file with the provided diff. + List of allowed tool names or a filter object. - - `"create_file"` + - `McpAllowedTools = array of string` - - `DeleteFile object { path, type }` + A string array of allowed tool names - Instruction describing how to delete a file via the apply_patch tool. + - `McpToolFilter object { read_only, tool_names }` - - `path: string` + A filter object to specify which tools are allowed. - Path of the file to delete. + - `read_only: optional boolean` - - `type: "delete_file"` + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. - Delete the specified file. + - `tool_names: optional array of string` - - `"delete_file"` + List of allowed tool names. - - `UpdateFile object { diff, path, type }` + - `authorization: optional string` - Instruction describing how to update a file via the apply_patch tool. + An OAuth access token that can be used with a remote MCP server, either + with a custom MCP server URL or a service connector. Your application + must handle the OAuth authorization flow and provide the token here. - - `diff: string` + - `connector_id: optional "connector_dropbox" or "connector_gmail" or "connector_googlecalendar" or 5 more` - Diff to apply. + Identifier for service connectors, like those available in ChatGPT. One of + `server_url` or `connector_id` must be provided. Learn more about service + connectors [here](/docs/guides/tools-remote-mcp#connectors). - - `path: string` + Currently supported `connector_id` values are: - Path of the file to update. + - Dropbox: `connector_dropbox` + - Gmail: `connector_gmail` + - Google Calendar: `connector_googlecalendar` + - Google Drive: `connector_googledrive` + - Microsoft Teams: `connector_microsoftteams` + - Outlook Calendar: `connector_outlookcalendar` + - Outlook Email: `connector_outlookemail` + - SharePoint: `connector_sharepoint` - - `type: "update_file"` + - `"connector_dropbox"` - Update an existing file with the provided diff. + - `"connector_gmail"` - - `"update_file"` + - `"connector_googlecalendar"` - - `status: "in_progress" or "completed"` + - `"connector_googledrive"` - The status of the apply patch tool call. One of `in_progress` or `completed`. + - `"connector_microsoftteams"` - - `"in_progress"` + - `"connector_outlookcalendar"` - - `"completed"` + - `"connector_outlookemail"` - - `type: "apply_patch_call"` + - `"connector_sharepoint"` - The type of the item. Always `apply_patch_call`. + - `defer_loading: optional boolean` - - `"apply_patch_call"` + Whether this MCP tool is deferred and discovered via tool search. - - `created_by: optional string` + - `headers: optional map[string]` - The ID of the entity that created this tool call. + Optional HTTP headers to send to the MCP server. Use for authentication + or other purposes. - - `ApplyPatchCallOutput object { id, call_id, status, 3 more }` + - `require_approval: optional object { always, never } or "always" or "never"` - The output emitted by an apply patch tool call. + Specify which of the MCP server's tools require approval. - - `id: string` + - `McpToolApprovalFilter object { always, never }` - The unique ID of the apply patch tool call output. Populated when this item is returned via API. + Specify which of the MCP server's tools require approval. Can be + `always`, `never`, or a filter object associated with tools + that require approval. - - `call_id: string` + - `always: optional object { read_only, tool_names }` - The unique ID of the apply patch tool call generated by the model. + A filter object to specify which tools are allowed. - - `status: "completed" or "failed"` + - `read_only: optional boolean` - The status of the apply patch tool call output. One of `completed` or `failed`. + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. - - `"completed"` + - `tool_names: optional array of string` - - `"failed"` + List of allowed tool names. - - `type: "apply_patch_call_output"` + - `never: optional object { read_only, tool_names }` - The type of the item. Always `apply_patch_call_output`. + A filter object to specify which tools are allowed. - - `"apply_patch_call_output"` + - `read_only: optional boolean` - - `created_by: optional string` + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. - The ID of the entity that created this tool call output. + - `tool_names: optional array of string` - - `output: optional string` + List of allowed tool names. - Optional textual output returned by the apply patch tool. + - `McpToolApprovalSetting = "always" or "never"` - - `McpListTools object { id, server_label, tools, 2 more }` + Specify a single approval policy for all tools. One of `always` or + `never`. When set to `always`, all tools will require approval. When + set to `never`, all tools will not require approval. - A list of tools available on an MCP server. + - `"always"` - - `id: string` + - `"never"` - The unique ID of the list. + - `server_description: optional string` - - `server_label: string` + Optional description of the MCP server, used to provide more context. - The label of the MCP server. + - `server_url: optional string` - - `tools: array of object { input_schema, name, annotations, description }` + The URL for the MCP server. One of `server_url` or `connector_id` must be + provided. - The tools available on the server. + - `CodeInterpreter object { container, type }` - - `input_schema: unknown` + A tool that runs Python code to help generate a response to a prompt. - The JSON schema describing the tool's input. + - `container: string or object { type, file_ids, memory_limit, network_policy }` - - `name: string` + The code interpreter container. Can be a container ID or an object that + specifies uploaded file IDs to make available to your code, along with an + optional `memory_limit` setting. - The name of the tool. + - `string` - - `annotations: optional unknown` + The container ID. - Additional annotations about the tool. + - `CodeInterpreterToolAuto object { type, file_ids, memory_limit, network_policy }` - - `description: optional string` + Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. - The description of the tool. + - `type: "auto"` - - `type: "mcp_list_tools"` + Always `auto`. - The type of the item. Always `mcp_list_tools`. + - `"auto"` - - `"mcp_list_tools"` + - `file_ids: optional array of string` - - `error: optional string` + An optional list of uploaded files to make available to your code. - Error message if the server could not list tools. + - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` - - `McpApprovalRequest object { id, arguments, name, 2 more }` + The memory limit for the code interpreter container. - A request for human approval of a tool invocation. + - `"1g"` - - `id: string` + - `"4g"` - The unique ID of the approval request. + - `"16g"` - - `arguments: string` + - `"64g"` - A JSON string of arguments for the tool. + - `network_policy: optional ContainerNetworkPolicyDisabled or ContainerNetworkPolicyAllowlist` - - `name: string` + Network access policy for the container. - The name of the tool to run. + - `ContainerNetworkPolicyDisabled object { type }` - - `server_label: string` + - `type: "disabled"` - The label of the MCP server making the request. + Disable outbound network access. Always `disabled`. - - `type: "mcp_approval_request"` + - `"disabled"` - The type of the item. Always `mcp_approval_request`. + - `ContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` - - `"mcp_approval_request"` + - `allowed_domains: array of string` - - `McpApprovalResponse object { id, approval_request_id, approve, 2 more }` + A list of allowed domains when type is `allowlist`. - A response to an MCP approval request. + - `type: "allowlist"` - - `id: string` + Allow outbound network access only to specified domains. Always `allowlist`. - The unique ID of the approval response + - `"allowlist"` - - `approval_request_id: string` + - `domain_secrets: optional array of ContainerNetworkPolicyDomainSecret` - The ID of the approval request being answered. + Optional domain-scoped secrets for allowlisted domains. - - `approve: boolean` + - `domain: string` - Whether the request was approved. + The domain associated with the secret. - - `type: "mcp_approval_response"` + - `name: string` - The type of the item. Always `mcp_approval_response`. + The name of the secret to inject for the domain. - - `"mcp_approval_response"` + - `value: string` - - `reason: optional string` + The secret value to inject for the domain. - Optional reason for the decision. + - `type: "code_interpreter"` - - `McpCall object { id, arguments, name, 6 more }` + The type of the code interpreter tool. Always `code_interpreter`. - An invocation of a tool on an MCP server. + - `"code_interpreter"` - - `id: string` + - `ImageGeneration object { type, action, background, 9 more }` - The unique ID of the tool call. + A tool that generates images using the GPT image models. - - `arguments: string` + - `type: "image_generation"` - A JSON string of the arguments passed to the tool. + The type of the image generation tool. Always `image_generation`. - - `name: string` + - `"image_generation"` - The name of the tool that was run. + - `action: optional "generate" or "edit" or "auto"` - - `server_label: string` + Whether to generate a new image or edit an existing image. Default: `auto`. - The label of the MCP server running the tool. + - `"generate"` - - `type: "mcp_call"` + - `"edit"` - The type of the item. Always `mcp_call`. + - `"auto"` - - `"mcp_call"` + - `background: optional "transparent" or "opaque" or "auto"` - - `approval_request_id: optional string` + Background type for the generated image. One of `transparent`, + `opaque`, or `auto`. Default: `auto`. - Unique identifier for the MCP tool call approval request. - Include this value in a subsequent `mcp_approval_response` input to approve or reject the corresponding tool call. + - `"transparent"` - - `error: optional string` + - `"opaque"` - The error from the tool call, if any. + - `"auto"` - - `output: optional string` + - `input_fidelity: optional "high" or "low"` - The output from the tool call. + Control how much effort the model will exert to match the style and features, especially facial features, of input images. This parameter is only supported for `gpt-image-1` and `gpt-image-1.5` and later models, unsupported for `gpt-image-1-mini`. Supports `high` and `low`. Defaults to `low`. - - `status: optional "in_progress" or "completed" or "incomplete" or 2 more` + - `"high"` - The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. + - `"low"` - - `"in_progress"` + - `input_image_mask: optional object { file_id, image_url }` - - `"completed"` + Optional mask for inpainting. Contains `image_url` + (string, optional) and `file_id` (string, optional). - - `"incomplete"` + - `file_id: optional string` - - `"calling"` + File ID for the mask image. - - `"failed"` + - `image_url: optional string` - - `CustomToolCall object { call_id, input, name, 3 more }` + Base64-encoded mask image. - A call to a custom tool created by the model. + - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` - - `call_id: string` + The image generation model to use. Default: `gpt-image-1`. - An identifier used to map this custom tool call to a tool call output. + - `string` - - `input: string` + - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` - The input for the custom tool call generated by the model. + The image generation model to use. Default: `gpt-image-1`. - - `name: string` + - `"gpt-image-1"` - The name of the custom tool being called. + - `"gpt-image-1-mini"` - - `type: "custom_tool_call"` + - `"gpt-image-1.5"` - The type of the custom tool call. Always `custom_tool_call`. + - `moderation: optional "auto" or "low"` - - `"custom_tool_call"` + Moderation level for the generated image. Default: `auto`. - - `id: optional string` + - `"auto"` - The unique ID of the custom tool call in the OpenAI platform. + - `"low"` - - `namespace: optional string` + - `output_compression: optional number` - The namespace of the custom tool being called. + Compression level for the output image. Default: 100. - - `CustomToolCallOutput object { call_id, output, type, id }` + - `output_format: optional "png" or "webp" or "jpeg"` - The output of a custom tool call from your code, being sent back to the model. + The output format of the generated image. One of `png`, `webp`, or + `jpeg`. Default: `png`. - - `call_id: string` + - `"png"` - The call ID, used to map this custom tool call output to a custom tool call. + - `"webp"` - - `output: string or array of ResponseInputText or ResponseInputImage or ResponseInputFile` + - `"jpeg"` - The output from the custom tool call generated by your code. - Can be a string or an list of output content. + - `partial_images: optional number` - - `StringOutput = string` + Number of partial images to generate in streaming mode, from 0 (default value) to 3. - A string of the output of the custom tool call. + - `quality: optional "low" or "medium" or "high" or "auto"` - - `OutputContentList = array of ResponseInputText or ResponseInputImage or ResponseInputFile` + The quality of the generated image. One of `low`, `medium`, `high`, + or `auto`. Default: `auto`. - Text, image, or file output of the custom tool call. + - `"low"` - - `ResponseInputText object { text, type }` + - `"medium"` - A text input to the model. + - `"high"` - - `ResponseInputImage object { detail, type, file_id, image_url }` + - `"auto"` - An image input to the model. Learn about [image inputs](/docs/guides/vision). + - `size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or "auto"` - - `ResponseInputFile object { type, detail, file_data, 3 more }` + The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. - A file input to the model. + - `string` - - `type: "custom_tool_call_output"` + - `"1024x1024" or "1024x1536" or "1536x1024" or "auto"` - The type of the custom tool call output. Always `custom_tool_call_output`. + The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. - - `"custom_tool_call_output"` + - `"1024x1024"` - - `id: optional string` + - `"1024x1536"` - The unique ID of the custom tool call output in the OpenAI platform. + - `"1536x1024"` -### Example + - `"auto"` -```http -curl https://api.openai.com/v1/conversations/$CONVERSATION_ID/items/$ITEM_ID \ - -H "Authorization: Bearer $OPENAI_API_KEY" -``` + - `LocalShell object { type }` -#### Response + A tool that allows the model to execute shell commands in a local environment. -```json -{ - "id": "id", - "content": [ - { - "text": "text", - "type": "input_text" - } - ], - "role": "unknown", - "status": "in_progress", - "type": "message", - "phase": "commentary" -} -``` + - `type: "local_shell"` -### Example + The type of the local shell tool. Always `local_shell`. -```http -curl https://api.openai.com/v1/conversations/conv_123/items/msg_abc \ - -H "Authorization: Bearer $OPENAI_API_KEY" -``` + - `"local_shell"` -#### Response + - `Shell object { type, environment }` -```json -{ - "type": "message", - "id": "msg_abc", - "status": "completed", - "role": "user", - "content": [ - {"type": "input_text", "text": "Hello!"} - ] -} -``` + A tool that allows the model to execute shell commands. -## Delete an item + - `type: "shell"` -**delete** `/conversations/{conversation_id}/items/{item_id}` + The type of the shell tool. Always `shell`. -Delete an item from a conversation with the given IDs. + - `"shell"` -### Path Parameters + - `environment: optional ContainerAuto or LocalEnvironment or ContainerReference` -- `conversation_id: string` + - `ContainerAuto object { type, file_ids, memory_limit, 2 more }` -- `item_id: string` + - `type: "container_auto"` -### Returns + Automatically creates a container for this request -- `Conversation object { id, created_at, metadata, object }` + - `"container_auto"` - - `id: string` + - `file_ids: optional array of string` - The unique ID of the conversation. + An optional list of uploaded files to make available to your code. - - `created_at: number` + - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` - The time at which the conversation was created, measured in seconds since the Unix epoch. + The memory limit for the container. - - `metadata: unknown` + - `"1g"` - Set of 16 key-value pairs that can be attached to an object. This can be useful for storing additional information about the object in a structured format, and querying for objects via API or the dashboard. - Keys are strings with a maximum length of 64 characters. Values are strings with a maximum length of 512 characters. + - `"4g"` - - `object: "conversation"` + - `"16g"` - The object type, which is always `conversation`. + - `"64g"` - - `"conversation"` + - `network_policy: optional ContainerNetworkPolicyDisabled or ContainerNetworkPolicyAllowlist` -### Example + Network access policy for the container. -```http -curl https://api.openai.com/v1/conversations/$CONVERSATION_ID/items/$ITEM_ID \ - -X DELETE \ - -H "Authorization: Bearer $OPENAI_API_KEY" -``` + - `ContainerNetworkPolicyDisabled object { type }` -#### Response + - `ContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` -```json -{ - "id": "id", - "created_at": 0, - "metadata": {}, - "object": "conversation" -} -``` + - `skills: optional array of SkillReference or InlineSkill` -### Example + An optional list of skills referenced by id or inline data. -```http -curl -X DELETE https://api.openai.com/v1/conversations/conv_123/items/msg_abc \ - -H "Authorization: Bearer $OPENAI_API_KEY" -``` + - `SkillReference object { skill_id, type, version }` -#### Response + - `skill_id: string` -```json -{ - "id": "conv_123", - "object": "conversation", - "created_at": 1741900000, - "metadata": {"topic": "demo"} -} -``` + The ID of the referenced skill. -## Domain Types + - `type: "skill_reference"` -### Conversation Item + References a skill created with the /v1/skills endpoint. -- `ConversationItem = Message or object { id, arguments, call_id, 5 more } or object { id, call_id, output, 3 more } or 22 more` + - `"skill_reference"` - 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). + - `version: optional string` - - `Message object { id, content, role, 3 more }` + Optional skill version. Use a positive integer or 'latest'. Omit for default. - A message to or from the model. + - `InlineSkill object { description, name, source, type }` - - `id: string` + - `description: string` - The unique ID of the message. + The description of the skill. - - `content: array of ResponseInputText or ResponseOutputText or TextContent or 6 more` + - `name: string` - The content of the message + The name of the skill. - - `ResponseInputText object { text, type }` + - `source: InlineSkillSource` - A text input to the model. + Inline skill payload - - `text: string` + - `data: string` - The text input to the model. + Base64-encoded skill zip bundle. - - `type: "input_text"` + - `media_type: "application/zip"` - The type of the input item. Always `input_text`. + The media type of the inline skill payload. Must be `application/zip`. - - `"input_text"` + - `"application/zip"` - - `ResponseOutputText object { annotations, logprobs, text, type }` + - `type: "base64"` - A text output from the model. + The type of the inline skill source. Must be `base64`. - - `annotations: array of object { file_id, filename, index, type } or object { end_index, start_index, title, 2 more } or object { container_id, end_index, file_id, 3 more } or object { file_id, index, type }` + - `"base64"` - The annotations of the text output. + - `type: "inline"` - - `FileCitation object { file_id, filename, index, type }` + Defines an inline skill for this request. - A citation to a file. + - `"inline"` - - `file_id: string` + - `LocalEnvironment object { type, skills }` - The ID of the file. + - `type: "local"` - - `filename: string` + Use a local computer environment. - The filename of the file cited. + - `"local"` - - `index: number` + - `skills: optional array of LocalSkill` - The index of the file in the list of files. + An optional list of skills. - - `type: "file_citation"` + - `description: string` - The type of the file citation. Always `file_citation`. + The description of the skill. - - `"file_citation"` + - `name: string` - - `URLCitation object { end_index, start_index, title, 2 more }` + The name of the skill. - A citation for a web resource used to generate a model response. + - `path: string` - - `end_index: number` + The path to the directory containing the skill. - The index of the last character of the URL citation in the message. + - `ContainerReference object { container_id, type }` - - `start_index: number` + - `container_id: string` - The index of the first character of the URL citation in the message. + The ID of the referenced container. - - `title: string` + - `type: "container_reference"` - The title of the web resource. + References a container created with the /v1/containers endpoint - - `type: "url_citation"` + - `"container_reference"` - The type of the URL citation. Always `url_citation`. + - `Custom object { name, type, defer_loading, 2 more }` - - `"url_citation"` + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) - - `url: string` + - `name: string` - The URL of the web resource. + The name of the custom tool, used to identify it in tool calls. - - `ContainerFileCitation object { container_id, end_index, file_id, 3 more }` + - `type: "custom"` - A citation for a container file used to generate a model response. + The type of the custom tool. Always `custom`. - - `container_id: string` + - `"custom"` - The ID of the container file. + - `defer_loading: optional boolean` - - `end_index: number` + Whether this tool should be deferred and discovered via tool search. - The index of the last character of the container file citation in the message. + - `description: optional string` - - `file_id: string` + Optional description of the custom tool, used to provide more context. - The ID of the file. + - `format: optional CustomToolInputFormat` - - `filename: string` + The input format for the custom tool. Default is unconstrained text. - The filename of the container file cited. + - `Text object { type }` - - `start_index: number` + Unconstrained free-form text. - The index of the first character of the container file citation in the message. + - `type: "text"` - - `type: "container_file_citation"` + Unconstrained text format. Always `text`. - The type of the container file citation. Always `container_file_citation`. + - `"text"` - - `"container_file_citation"` + - `Grammar object { definition, syntax, type }` - - `FilePath object { file_id, index, type }` + A grammar defined by the user. - A path to a file. + - `definition: string` - - `file_id: string` + The grammar definition. - The ID of the file. + - `syntax: "lark" or "regex"` - - `index: number` + The syntax of the grammar definition. One of `lark` or `regex`. - The index of the file in the list of files. + - `"lark"` - - `type: "file_path"` + - `"regex"` - The type of the file path. Always `file_path`. + - `type: "grammar"` - - `"file_path"` + Grammar format. Always `grammar`. - - `logprobs: array of object { token, bytes, logprob, top_logprobs }` + - `"grammar"` - - `token: string` + - `Namespace object { description, name, tools, type }` - - `bytes: array of number` + Groups function/custom tools under a shared namespace. - - `logprob: number` + - `description: string` - - `top_logprobs: array of object { token, bytes, logprob }` + A description of the namespace shown to the model. - - `token: string` + - `name: string` - - `bytes: array of number` + The namespace name used in tool calls (for example, `crm`). - - `logprob: number` + - `tools: array of object { name, type, defer_loading, 3 more } or object { name, type, defer_loading, 2 more }` - - `text: string` + The function/custom tools available inside this namespace. - The text output from the model. + - `Function object { name, type, defer_loading, 3 more }` - - `type: "output_text"` + - `name: string` - The type of the output text. Always `output_text`. + - `type: "function"` - - `"output_text"` + - `"function"` - - `TextContent object { text, type }` + - `defer_loading: optional boolean` - A text content. + Whether this function should be deferred and discovered via tool search. - - `text: string` + - `description: optional string` - - `type: "text"` + - `parameters: optional unknown` - - `"text"` + - `strict: optional boolean` - - `SummaryTextContent object { text, type }` + - `Custom object { name, type, defer_loading, 2 more }` - A summary text from the model. + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) - - `text: string` + - `name: string` - A summary of the reasoning output from the model so far. + The name of the custom tool, used to identify it in tool calls. - - `type: "summary_text"` + - `type: "custom"` - The type of the object. Always `summary_text`. + The type of the custom tool. Always `custom`. - - `"summary_text"` + - `"custom"` - - `ReasoningText object { text, type }` + - `defer_loading: optional boolean` - Reasoning text from the model. + Whether this tool should be deferred and discovered via tool search. - - `text: string` + - `description: optional string` - The reasoning text from the model. + Optional description of the custom tool, used to provide more context. - - `type: "reasoning_text"` + - `format: optional CustomToolInputFormat` - The type of the reasoning text. Always `reasoning_text`. + The input format for the custom tool. Default is unconstrained text. - - `"reasoning_text"` + - `type: "namespace"` - - `ResponseOutputRefusal object { refusal, type }` + The type of the tool. Always `namespace`. - A refusal from the model. + - `"namespace"` - - `refusal: string` + - `ToolSearch object { type, description, execution, parameters }` - The refusal explanation from the model. + Hosted or BYOT tool search configuration for deferred tools. - - `type: "refusal"` + - `type: "tool_search"` - The type of the refusal. Always `refusal`. + The type of the tool. Always `tool_search`. - - `"refusal"` + - `"tool_search"` - - `ResponseInputImage object { detail, type, file_id, image_url }` + - `description: optional string` - An image input to the model. Learn about [image inputs](/docs/guides/vision). + Description shown to the model for a client-executed tool search tool. - - `detail: "low" or "high" or "auto" or "original"` + - `execution: optional "server" or "client"` - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + Whether tool search is executed by the server or by the client. - - `"low"` + - `"server"` - - `"high"` + - `"client"` - - `"auto"` + - `parameters: optional unknown` - - `"original"` + Parameter schema for a client-executed tool search tool. - - `type: "input_image"` + - `WebSearchPreview object { type, search_content_types, search_context_size, user_location }` - The type of the input item. Always `input_image`. + This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - - `"input_image"` + - `type: "web_search_preview" or "web_search_preview_2025_03_11"` - - `file_id: optional string` + The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. - The ID of the file to be sent to the model. + - `"web_search_preview"` - - `image_url: optional string` + - `"web_search_preview_2025_03_11"` - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + - `search_content_types: optional array of "text" or "image"` - - `ComputerScreenshotContent object { detail, file_id, image_url, type }` + - `"text"` - A screenshot of a computer. + - `"image"` - - `detail: "low" or "high" or "auto" or "original"` + - `search_context_size: optional "low" or "medium" or "high"` - The detail level of the screenshot image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. - `"low"` + - `"medium"` + - `"high"` - - `"auto"` + - `user_location: optional object { type, city, country, 2 more }` - - `"original"` + The user's location. - - `file_id: string` + - `type: "approximate"` - The identifier of an uploaded file that contains the screenshot. + The type of location approximation. Always `approximate`. - - `image_url: string` + - `"approximate"` - The URL of the screenshot image. + - `city: optional string` - - `type: "computer_screenshot"` + Free text input for the city of the user, e.g. `San Francisco`. - Specifies the event type. For a computer screenshot, this property is always set to `computer_screenshot`. + - `country: optional string` - - `"computer_screenshot"` + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - - `ResponseInputFile object { type, detail, file_data, 3 more }` + - `region: optional string` - A file input to the model. + Free text input for the region of the user, e.g. `California`. - - `type: "input_file"` + - `timezone: optional string` - The type of the input item. Always `input_file`. + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - - `"input_file"` + - `ApplyPatch object { type }` - - `detail: optional "low" or "high"` + Allows the assistant to create, delete, or update files using unified diffs. - 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`. + - `type: "apply_patch"` - - `"low"` + The type of the tool. Always `apply_patch`. - - `"high"` + - `"apply_patch"` - - `file_data: optional string` + - `type: "tool_search_output"` - The content of the file to be sent to the model. + The type of the item. Always `tool_search_output`. - - `file_id: optional string` + - `"tool_search_output"` - The ID of the file to be sent to the model. + - `created_by: optional string` - - `file_url: optional string` + The identifier of the actor that created the item. - The URL of the file to be sent to the model. + - `AdditionalTools object { id, role, tools, type }` - - `filename: optional string` + - `id: string` - The name of the file to be sent to the model. + The unique ID of the additional tools item. - `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`. + The role that provided the additional tools. - `"unknown"` @@ -15514,1862 +21025,1842 @@ curl -X DELETE https://api.openai.com/v1/conversations/conv_123/items/msg_abc \ - `"tool"` - - `status: "in_progress" or "completed" or "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` + + The additional tool definitions made available at this item. + + - `Function object { name, parameters, strict, 3 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). - The status of item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. + - `name: string` - - `"in_progress"` + The name of the function to call. - - `"completed"` + - `parameters: map[unknown]` - - `"incomplete"` + A JSON schema object describing the parameters of the function. - - `type: "message"` + - `strict: boolean` - The type of the message. Always set to `message`. + Whether to enforce strict parameter validation. Default `true`. - - `"message"` + - `type: "function"` - - `phase: optional "commentary" or "final_answer"` + The type of the function tool. Always `function`. - Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend phase on all assistant messages — dropping it can degrade performance. Not used for user messages. + - `"function"` - - `"commentary"` + - `defer_loading: optional boolean` - - `"final_answer"` + Whether this function is deferred and loaded via tool search. - - `FunctionCall object { id, arguments, call_id, 5 more }` + - `description: optional string` - - `id: string` + A description of the function. Used by the model to determine whether or not to call the function. - The unique ID of the function tool call. + - `FileSearch object { type, vector_store_ids, filters, 2 more }` - - `arguments: string` + 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). - A JSON string of the arguments to pass to the function. + - `type: "file_search"` - - `call_id: string` + The type of the file search tool. Always `file_search`. - The unique ID of the function tool call generated by the model. + - `"file_search"` - - `name: string` + - `vector_store_ids: array of string` - The name of the function to run. + The IDs of the vector stores to search. - - `status: "in_progress" or "completed" or "incomplete"` + - `filters: optional ComparisonFilter or CompoundFilter` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + A filter to apply. - - `"in_progress"` + - `ComparisonFilter object { key, type, value }` - - `"completed"` + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - - `"incomplete"` + - `CompoundFilter object { filters, type }` - - `type: "function_call"` + Combine multiple filters using `and` or `or`. - The type of the function tool call. Always `function_call`. + - `max_num_results: optional number` - - `"function_call"` + The maximum number of results to return. This number should be between 1 and 50 inclusive. - - `created_by: optional string` + - `ranking_options: optional object { hybrid_search, ranker, score_threshold }` - The identifier of the actor that created the item. + Ranking options for search. - - `namespace: optional string` + - `hybrid_search: optional object { embedding_weight, text_weight }` - The namespace of the function to run. + Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. - - `FunctionCallOutput object { id, call_id, output, 3 more }` + - `embedding_weight: number` - - `id: string` + The weight of the embedding in the reciprocal ranking fusion. - The unique ID of the function call tool output. + - `text_weight: number` - - `call_id: string` + The weight of the text in the reciprocal ranking fusion. - The unique ID of the function tool call generated by the model. + - `ranker: optional "auto" or "default-2024-11-15"` - - `output: string or array of ResponseInputText or ResponseInputImage or ResponseInputFile` + The ranker to use for the file search. - The output from the function call generated by your code. - Can be a string or an list of output content. + - `"auto"` - - `StringOutput = string` + - `"default-2024-11-15"` - A string of the output of the function call. + - `score_threshold: optional number` - - `OutputContentList = array of ResponseInputText or ResponseInputImage or ResponseInputFile` + The score threshold for the file search, a number between 0 and 1. Numbers closer to 1 will attempt to return only the most relevant results, but may return fewer results. - Text, image, or file output of the function call. + - `Computer object { type }` - - `ResponseInputText object { text, type }` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - A text input to the model. + - `type: "computer"` - - `ResponseInputImage object { detail, type, file_id, image_url }` + The type of the computer tool. Always `computer`. - An image input to the model. Learn about [image inputs](/docs/guides/vision). + - `"computer"` - - `ResponseInputFile object { type, detail, file_data, 3 more }` + - `ComputerUsePreview object { display_height, display_width, environment, type }` - A file input to the model. + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `status: "in_progress" or "completed" or "incomplete"` + - `display_height: number` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + The height of the computer display. - - `"in_progress"` + - `display_width: number` - - `"completed"` + The width of the computer display. - - `"incomplete"` + - `environment: "windows" or "mac" or "linux" or 2 more` - - `type: "function_call_output"` + The type of computer environment to control. - The type of the function tool call output. Always `function_call_output`. + - `"windows"` - - `"function_call_output"` + - `"mac"` - - `created_by: optional string` + - `"linux"` - The identifier of the actor that created the item. + - `"ubuntu"` - - `FileSearchCall object { id, queries, status, 2 more }` + - `"browser"` - The results of a file search tool call. See the - [file search guide](/docs/guides/tools-file-search) for more information. + - `type: "computer_use_preview"` - - `id: string` + The type of the computer use tool. Always `computer_use_preview`. - The unique ID of the file search tool call. + - `"computer_use_preview"` - - `queries: array of string` + - `WebSearch object { type, filters, search_context_size, user_location }` - The queries used to search for files. + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](/docs/guides/tools-web-search). - - `status: "in_progress" or "searching" or "completed" or 2 more` + - `type: "web_search" or "web_search_2025_08_26"` - The status of the file search tool call. One of `in_progress`, - `searching`, `incomplete` or `failed`, + The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. - - `"in_progress"` + - `"web_search"` - - `"searching"` + - `"web_search_2025_08_26"` - - `"completed"` + - `filters: optional object { allowed_domains }` - - `"incomplete"` + Filters for the search. - - `"failed"` + - `allowed_domains: optional array of string` - - `type: "file_search_call"` + Allowed domains for the search. If not provided, all domains are allowed. + Subdomains of the provided domains are allowed as well. - The type of the file search tool call. Always `file_search_call`. + Example: `["pubmed.ncbi.nlm.nih.gov"]` - - `"file_search_call"` + - `search_context_size: optional "low" or "medium" or "high"` - - `results: optional array of object { attributes, file_id, filename, 2 more }` + High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. - The results of the file search tool call. + - `"low"` - - `attributes: optional map[string or number or boolean]` + - `"medium"` - Set of 16 key-value pairs that can be attached to an object. This can be - useful for storing additional information about the object in a structured - format, and querying for objects via API or the dashboard. Keys are strings - with a maximum length of 64 characters. Values are strings with a maximum - length of 512 characters, booleans, or numbers. + - `"high"` - - `string` + - `user_location: optional object { city, country, region, 2 more }` - - `number` + The approximate location of the user. - - `boolean` + - `city: optional string` - - `file_id: optional string` + Free text input for the city of the user, e.g. `San Francisco`. - The unique ID of the file. + - `country: optional string` - - `filename: optional string` + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - The name of the file. + - `region: optional string` - - `score: optional number` + Free text input for the region of the user, e.g. `California`. - The relevance score of the file - a value between 0 and 1. + - `timezone: optional string` - - `text: optional string` + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - The text that was retrieved from the file. + - `type: optional "approximate"` - - `WebSearchCall object { id, action, status, type }` + The type of location approximation. Always `approximate`. - The results of a web search tool call. See the - [web search guide](/docs/guides/tools-web-search) for more information. + - `"approximate"` - - `id: string` + - `Mcp object { server_label, type, allowed_tools, 7 more }` - The unique ID of the web search tool call. + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](/docs/guides/tools-remote-mcp). - - `action: object { query, type, queries, sources } or object { type, url } or object { pattern, type, url }` + - `server_label: string` - An object describing the specific action taken in this web search call. - Includes details on how the model used the web (search, open_page, find_in_page). + A label for this MCP server, used to identify it in tool calls. - - `Search object { query, type, queries, sources }` + - `type: "mcp"` - Action type "search" - Performs a web search query. + The type of the MCP tool. Always `mcp`. - - `query: string` + - `"mcp"` - [DEPRECATED] The search query. + - `allowed_tools: optional array of string or object { read_only, tool_names }` - - `type: "search"` + List of allowed tool names or a filter object. - The action type. + - `McpAllowedTools = array of string` - - `"search"` + A string array of allowed tool names - - `queries: optional array of string` + - `McpToolFilter object { read_only, tool_names }` - The search queries. + A filter object to specify which tools are allowed. - - `sources: optional array of object { type, url }` + - `read_only: optional boolean` - The sources used in the search. + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. - - `type: "url"` + - `tool_names: optional array of string` - The type of source. Always `url`. + List of allowed tool names. - - `"url"` + - `authorization: optional string` - - `url: string` + An OAuth access token that can be used with a remote MCP server, either + with a custom MCP server URL or a service connector. Your application + must handle the OAuth authorization flow and provide the token here. - The URL of the source. + - `connector_id: optional "connector_dropbox" or "connector_gmail" or "connector_googlecalendar" or 5 more` - - `OpenPage object { type, url }` + Identifier for service connectors, like those available in ChatGPT. One of + `server_url` or `connector_id` must be provided. Learn more about service + connectors [here](/docs/guides/tools-remote-mcp#connectors). - Action type "open_page" - Opens a specific URL from search results. + Currently supported `connector_id` values are: - - `type: "open_page"` + - Dropbox: `connector_dropbox` + - Gmail: `connector_gmail` + - Google Calendar: `connector_googlecalendar` + - Google Drive: `connector_googledrive` + - Microsoft Teams: `connector_microsoftteams` + - Outlook Calendar: `connector_outlookcalendar` + - Outlook Email: `connector_outlookemail` + - SharePoint: `connector_sharepoint` - The action type. + - `"connector_dropbox"` - - `"open_page"` + - `"connector_gmail"` - - `url: optional string` + - `"connector_googlecalendar"` - The URL opened by the model. + - `"connector_googledrive"` - - `FindInPage object { pattern, type, url }` + - `"connector_microsoftteams"` - Action type "find_in_page": Searches for a pattern within a loaded page. + - `"connector_outlookcalendar"` - - `pattern: string` + - `"connector_outlookemail"` - The pattern or text to search for within the page. + - `"connector_sharepoint"` - - `type: "find_in_page"` + - `defer_loading: optional boolean` - The action type. + Whether this MCP tool is deferred and discovered via tool search. - - `"find_in_page"` + - `headers: optional map[string]` - - `url: string` + Optional HTTP headers to send to the MCP server. Use for authentication + or other purposes. - The URL of the page searched for the pattern. + - `require_approval: optional object { always, never } or "always" or "never"` - - `status: "in_progress" or "searching" or "completed" or "failed"` + Specify which of the MCP server's tools require approval. - The status of the web search tool call. + - `McpToolApprovalFilter object { always, never }` - - `"in_progress"` + Specify which of the MCP server's tools require approval. Can be + `always`, `never`, or a filter object associated with tools + that require approval. - - `"searching"` + - `always: optional object { read_only, tool_names }` - - `"completed"` + A filter object to specify which tools are allowed. - - `"failed"` + - `read_only: optional boolean` - - `type: "web_search_call"` + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. - The type of the web search tool call. Always `web_search_call`. + - `tool_names: optional array of string` - - `"web_search_call"` + List of allowed tool names. - - `ImageGenerationCall object { id, result, status, type }` + - `never: optional object { read_only, tool_names }` - An image generation request made by the model. + A filter object to specify which tools are allowed. - - `id: string` + - `read_only: optional boolean` - The unique ID of the image generation call. + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. - - `result: string` + - `tool_names: optional array of string` - The generated image encoded in base64. + List of allowed tool names. - - `status: "in_progress" or "completed" or "generating" or "failed"` + - `McpToolApprovalSetting = "always" or "never"` - The status of the image generation call. + Specify a single approval policy for all tools. One of `always` or + `never`. When set to `always`, all tools will require approval. When + set to `never`, all tools will not require approval. - - `"in_progress"` + - `"always"` - - `"completed"` + - `"never"` - - `"generating"` + - `server_description: optional string` - - `"failed"` + Optional description of the MCP server, used to provide more context. - - `type: "image_generation_call"` + - `server_url: optional string` - The type of the image generation call. Always `image_generation_call`. + The URL for the MCP server. One of `server_url` or `connector_id` must be + provided. - - `"image_generation_call"` + - `CodeInterpreter object { container, type }` - - `ComputerCall object { id, call_id, pending_safety_checks, 4 more }` + A tool that runs Python code to help generate a response to a prompt. - A tool call to a computer use tool. See the - [computer use guide](/docs/guides/tools-computer-use) for more information. + - `container: string or object { type, file_ids, memory_limit, network_policy }` - - `id: string` + The code interpreter container. Can be a container ID or an object that + specifies uploaded file IDs to make available to your code, along with an + optional `memory_limit` setting. - The unique ID of the computer call. + - `string` - - `call_id: string` + The container ID. - An identifier used when responding to the tool call with output. + - `CodeInterpreterToolAuto object { type, file_ids, memory_limit, network_policy }` - - `pending_safety_checks: array of object { id, code, message }` + Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. - The pending safety checks for the computer call. + - `type: "auto"` - - `id: string` + Always `auto`. - The ID of the pending safety check. + - `"auto"` - - `code: optional string` + - `file_ids: optional array of string` - The type of the pending safety check. + An optional list of uploaded files to make available to your code. - - `message: optional string` + - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` - Details about the pending safety check. + The memory limit for the code interpreter container. - - `status: "in_progress" or "completed" or "incomplete"` + - `"1g"` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `"4g"` - - `"in_progress"` + - `"16g"` - - `"completed"` + - `"64g"` - - `"incomplete"` + - `network_policy: optional ContainerNetworkPolicyDisabled or ContainerNetworkPolicyAllowlist` - - `type: "computer_call"` + Network access policy for the container. - The type of the computer call. Always `computer_call`. + - `ContainerNetworkPolicyDisabled object { type }` - - `"computer_call"` + - `ContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` - - `action: optional ComputerAction` + - `type: "code_interpreter"` - A click action. + The type of the code interpreter tool. Always `code_interpreter`. - - `Click object { button, type, x, 2 more }` + - `"code_interpreter"` - A click action. + - `ImageGeneration object { type, action, background, 9 more }` - - `button: "left" or "right" or "wheel" or 2 more` + A tool that generates images using the GPT image models. - Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. + - `type: "image_generation"` - - `"left"` + The type of the image generation tool. Always `image_generation`. - - `"right"` + - `"image_generation"` - - `"wheel"` + - `action: optional "generate" or "edit" or "auto"` - - `"back"` + Whether to generate a new image or edit an existing image. Default: `auto`. - - `"forward"` + - `"generate"` - - `type: "click"` + - `"edit"` - Specifies the event type. For a click action, this property is always `click`. + - `"auto"` - - `"click"` + - `background: optional "transparent" or "opaque" or "auto"` - - `x: number` + Background type for the generated image. One of `transparent`, + `opaque`, or `auto`. Default: `auto`. - The x-coordinate where the click occurred. + - `"transparent"` - - `y: number` + - `"opaque"` - The y-coordinate where the click occurred. + - `"auto"` - - `keys: optional array of string` + - `input_fidelity: optional "high" or "low"` - The keys being held while clicking. + Control how much effort the model will exert to match the style and features, especially facial features, of input images. This parameter is only supported for `gpt-image-1` and `gpt-image-1.5` and later models, unsupported for `gpt-image-1-mini`. Supports `high` and `low`. Defaults to `low`. - - `DoubleClick object { keys, type, x, y }` + - `"high"` - A double click action. + - `"low"` - - `keys: array of string` + - `input_image_mask: optional object { file_id, image_url }` - The keys being held while double-clicking. + Optional mask for inpainting. Contains `image_url` + (string, optional) and `file_id` (string, optional). - - `type: "double_click"` + - `file_id: optional string` - Specifies the event type. For a double click action, this property is always set to `double_click`. + File ID for the mask image. - - `"double_click"` + - `image_url: optional string` - - `x: number` + Base64-encoded mask image. - The x-coordinate where the double click occurred. + - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` - - `y: number` + The image generation model to use. Default: `gpt-image-1`. - The y-coordinate where the double click occurred. + - `string` - - `Drag object { path, type, keys }` + - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` - A drag action. + The image generation model to use. Default: `gpt-image-1`. - - `path: array of object { x, y }` + - `"gpt-image-1"` - An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg + - `"gpt-image-1-mini"` - ``` - [ - { x: 100, y: 200 }, - { x: 200, y: 300 } - ] - ``` + - `"gpt-image-1.5"` - - `x: number` + - `moderation: optional "auto" or "low"` - The x-coordinate. + Moderation level for the generated image. Default: `auto`. - - `y: number` + - `"auto"` - The y-coordinate. + - `"low"` - - `type: "drag"` + - `output_compression: optional number` - Specifies the event type. For a drag action, this property is always set to `drag`. + Compression level for the output image. Default: 100. - - `"drag"` + - `output_format: optional "png" or "webp" or "jpeg"` - - `keys: optional array of string` + The output format of the generated image. One of `png`, `webp`, or + `jpeg`. Default: `png`. - The keys being held while dragging the mouse. + - `"png"` - - `Keypress object { keys, type }` + - `"webp"` - A collection of keypresses the model would like to perform. + - `"jpeg"` - - `keys: array of string` + - `partial_images: optional number` - The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. + Number of partial images to generate in streaming mode, from 0 (default value) to 3. - - `type: "keypress"` + - `quality: optional "low" or "medium" or "high" or "auto"` - Specifies the event type. For a keypress action, this property is always set to `keypress`. + The quality of the generated image. One of `low`, `medium`, `high`, + or `auto`. Default: `auto`. - - `"keypress"` + - `"low"` - - `Move object { type, x, y, keys }` + - `"medium"` - A mouse move action. + - `"high"` - - `type: "move"` + - `"auto"` - Specifies the event type. For a move action, this property is always set to `move`. + - `size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or "auto"` - - `"move"` + The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. - - `x: number` + - `string` - The x-coordinate to move to. + - `"1024x1024" or "1024x1536" or "1536x1024" or "auto"` - - `y: number` + The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. - The y-coordinate to move to. + - `"1024x1024"` - - `keys: optional array of string` + - `"1024x1536"` - The keys being held while moving the mouse. + - `"1536x1024"` - - `Screenshot object { type }` + - `"auto"` - A screenshot action. + - `LocalShell object { type }` - - `type: "screenshot"` + A tool that allows the model to execute shell commands in a local environment. - Specifies the event type. For a screenshot action, this property is always set to `screenshot`. + - `type: "local_shell"` - - `"screenshot"` + The type of the local shell tool. Always `local_shell`. - - `Scroll object { scroll_x, scroll_y, type, 3 more }` + - `"local_shell"` - A scroll action. + - `Shell object { type, environment }` - - `scroll_x: number` + A tool that allows the model to execute shell commands. - The horizontal scroll distance. + - `type: "shell"` - - `scroll_y: number` + The type of the shell tool. Always `shell`. - The vertical scroll distance. + - `"shell"` - - `type: "scroll"` + - `environment: optional ContainerAuto or LocalEnvironment or ContainerReference` - Specifies the event type. For a scroll action, this property is always set to `scroll`. + - `ContainerAuto object { type, file_ids, memory_limit, 2 more }` - - `"scroll"` + - `LocalEnvironment object { type, skills }` - - `x: number` + - `ContainerReference object { container_id, type }` - The x-coordinate where the scroll occurred. + - `Custom object { name, type, defer_loading, 2 more }` - - `y: number` + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) - The y-coordinate where the scroll occurred. + - `name: string` - - `keys: optional array of string` + The name of the custom tool, used to identify it in tool calls. - The keys being held while scrolling. + - `type: "custom"` - - `Type object { text, type }` + The type of the custom tool. Always `custom`. - An action to type in text. + - `"custom"` - - `text: string` + - `defer_loading: optional boolean` - The text to type. + Whether this tool should be deferred and discovered via tool search. - - `type: "type"` + - `description: optional string` - Specifies the event type. For a type action, this property is always set to `type`. + Optional description of the custom tool, used to provide more context. - - `"type"` + - `format: optional CustomToolInputFormat` - - `Wait object { type }` + The input format for the custom tool. Default is unconstrained text. - A wait action. + - `Namespace object { description, name, tools, type }` - - `type: "wait"` + Groups function/custom tools under a shared namespace. - Specifies the event type. For a wait action, this property is always set to `wait`. + - `description: string` - - `"wait"` + A description of the namespace shown to the model. - - `actions: optional ComputerActionList` + - `name: string` - Flattened batched actions for `computer_use`. Each action includes an - `type` discriminator and action-specific fields. + The namespace name used in tool calls (for example, `crm`). - - `Click object { button, type, x, 2 more }` + - `tools: array of object { name, type, defer_loading, 3 more } or object { name, type, defer_loading, 2 more }` - A click action. + The function/custom tools available inside this namespace. - - `DoubleClick object { keys, type, x, y }` + - `Function object { name, type, defer_loading, 3 more }` - A double click action. + - `name: string` - - `Drag object { path, type, keys }` + - `type: "function"` - A drag action. + - `"function"` - - `Keypress object { keys, type }` + - `defer_loading: optional boolean` - A collection of keypresses the model would like to perform. + Whether this function should be deferred and discovered via tool search. - - `Move object { type, x, y, keys }` + - `description: optional string` - A mouse move action. + - `parameters: optional unknown` - - `Screenshot object { type }` + - `strict: optional boolean` - A screenshot action. + - `Custom object { name, type, defer_loading, 2 more }` - - `Scroll object { scroll_x, scroll_y, type, 3 more }` + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) - A scroll action. + - `name: string` - - `Type object { text, type }` + The name of the custom tool, used to identify it in tool calls. - An action to type in text. + - `type: "custom"` - - `Wait object { type }` + The type of the custom tool. Always `custom`. - A wait action. + - `"custom"` - - `ComputerCallOutput object { id, call_id, output, 4 more }` + - `defer_loading: optional boolean` - - `id: string` + Whether this tool should be deferred and discovered via tool search. - The unique ID of the computer call tool output. + - `description: optional string` - - `call_id: string` + Optional description of the custom tool, used to provide more context. - The ID of the computer tool call that produced the output. + - `format: optional CustomToolInputFormat` - - `output: ResponseComputerToolCallOutputScreenshot` + The input format for the custom tool. Default is unconstrained text. - A computer screenshot image used with the computer use tool. + - `type: "namespace"` - - `type: "computer_screenshot"` + The type of the tool. Always `namespace`. - Specifies the event type. For a computer screenshot, this property is - always set to `computer_screenshot`. + - `"namespace"` - - `"computer_screenshot"` + - `ToolSearch object { type, description, execution, parameters }` - - `file_id: optional string` + Hosted or BYOT tool search configuration for deferred tools. - The identifier of an uploaded file that contains the screenshot. + - `type: "tool_search"` - - `image_url: optional string` + The type of the tool. Always `tool_search`. - The URL of the screenshot image. + - `"tool_search"` - - `status: "completed" or "incomplete" or "failed" or "in_progress"` + - `description: optional string` - The status of the message input. One of `in_progress`, `completed`, or - `incomplete`. Populated when input items are returned via API. + Description shown to the model for a client-executed tool search tool. - - `"completed"` + - `execution: optional "server" or "client"` - - `"incomplete"` + Whether tool search is executed by the server or by the client. - - `"failed"` + - `"server"` - - `"in_progress"` + - `"client"` - - `type: "computer_call_output"` + - `parameters: optional unknown` - The type of the computer tool call output. Always `computer_call_output`. + Parameter schema for a client-executed tool search tool. - - `"computer_call_output"` + - `WebSearchPreview object { type, search_content_types, search_context_size, user_location }` - - `acknowledged_safety_checks: optional array of object { id, code, message }` + This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - The safety checks reported by the API that have been acknowledged by the - developer. + - `type: "web_search_preview" or "web_search_preview_2025_03_11"` - - `id: string` + The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. - The ID of the pending safety check. + - `"web_search_preview"` - - `code: optional string` + - `"web_search_preview_2025_03_11"` - The type of the pending safety check. + - `search_content_types: optional array of "text" or "image"` - - `message: optional string` + - `"text"` - Details about the pending safety check. + - `"image"` - - `created_by: optional string` + - `search_context_size: optional "low" or "medium" or "high"` - The identifier of the actor that created the item. + High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. - - `ToolSearchCall object { id, arguments, call_id, 4 more }` + - `"low"` - - `id: string` + - `"medium"` - The unique ID of the tool search call item. + - `"high"` - - `arguments: unknown` + - `user_location: optional object { type, city, country, 2 more }` - Arguments used for the tool search call. + The user's location. - - `call_id: string` + - `type: "approximate"` - The unique ID of the tool search call generated by the model. + The type of location approximation. Always `approximate`. - - `execution: "server" or "client"` + - `"approximate"` - Whether tool search was executed by the server or by the client. + - `city: optional string` - - `"server"` + Free text input for the city of the user, e.g. `San Francisco`. - - `"client"` + - `country: optional string` - - `status: "in_progress" or "completed" or "incomplete"` + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - The status of the tool search call item that was recorded. + - `region: optional string` - - `"in_progress"` + Free text input for the region of the user, e.g. `California`. - - `"completed"` + - `timezone: optional string` - - `"incomplete"` + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - - `type: "tool_search_call"` + - `ApplyPatch object { type }` - The type of the item. Always `tool_search_call`. + Allows the assistant to create, delete, or update files using unified diffs. - - `"tool_search_call"` + - `type: "apply_patch"` - - `created_by: optional string` + The type of the tool. Always `apply_patch`. - The identifier of the actor that created the item. + - `"apply_patch"` - - `ToolSearchOutput object { id, call_id, execution, 4 more }` + - `type: "additional_tools"` - - `id: string` + The type of the item. Always `additional_tools`. - The unique ID of the tool search output item. + - `"additional_tools"` - - `call_id: string` + - `Reasoning object { id, summary, type, 3 more }` - The unique ID of the tool search call generated by the model. + 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). - - `execution: "server" or "client"` + - `id: string` - Whether tool search was executed by the server or by the client. + The unique identifier of the reasoning content. - - `"server"` + - `summary: array of SummaryTextContent` - - `"client"` + Reasoning summary content. - - `status: "in_progress" or "completed" or "incomplete"` + - `text: string` - The status of the tool search output item that was recorded. + A summary of the reasoning output from the model so far. - - `"in_progress"` + - `type: "summary_text"` - - `"completed"` + The type of the object. Always `summary_text`. - - `"incomplete"` + - `type: "reasoning"` - - `tools: array of object { name, parameters, strict, 3 more } or object { type, vector_store_ids, filters, 2 more } or object { type } or 12 more` + The type of the object. Always `reasoning`. - The loaded tool definitions returned by tool search. + - `"reasoning"` - - `Function object { name, parameters, strict, 3 more }` + - `content: optional array of object { text, type }` - 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). + Reasoning text content. - - `name: string` + - `text: string` - The name of the function to call. + The reasoning text from the model. - - `parameters: map[unknown]` + - `type: "reasoning_text"` - A JSON schema object describing the parameters of the function. + The type of the reasoning text. Always `reasoning_text`. - - `strict: boolean` + - `"reasoning_text"` - Whether to enforce strict parameter validation. Default `true`. + - `encrypted_content: optional string` - - `type: "function"` + The encrypted content of the reasoning item - populated when a response is + generated with `reasoning.encrypted_content` in the `include` parameter. - The type of the function tool. Always `function`. + - `status: optional "in_progress" or "completed" or "incomplete"` - - `"function"` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `defer_loading: optional boolean` + - `"in_progress"` - Whether this function is deferred and loaded via tool search. + - `"completed"` - - `description: optional string` + - `"incomplete"` - A description of the function. Used by the model to determine whether or not to call the function. + - `Compaction object { id, encrypted_content, type, created_by }` - - `FileSearch object { type, vector_store_ids, filters, 2 more }` + A compaction item generated by the [`v1/responses/compact` API](/docs/api-reference/responses/compact). - 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). + - `id: string` - - `type: "file_search"` + The unique ID of the compaction item. - The type of the file search tool. Always `file_search`. + - `encrypted_content: string` - - `"file_search"` + The encrypted content that was produced by compaction. - - `vector_store_ids: array of string` + - `type: "compaction"` - The IDs of the vector stores to search. + The type of the item. Always `compaction`. - - `filters: optional ComparisonFilter or CompoundFilter` + - `"compaction"` - A filter to apply. + - `created_by: optional string` - - `ComparisonFilter object { key, type, value }` + The identifier of the actor that created the item. - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + - `CodeInterpreterCall object { id, code, container_id, 3 more }` - - `key: string` + A tool call to run code. - The key to compare against the value. + - `id: string` - - `type: "eq" or "ne" or "gt" or 5 more` + The unique ID of the code interpreter tool call. - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + - `code: string` - - `eq`: equals - - `ne`: not equal - - `gt`: greater than - - `gte`: greater than or equal - - `lt`: less than - - `lte`: less than or equal - - `in`: in - - `nin`: not in + The code to run, or null if not available. - - `"eq"` + - `container_id: string` - - `"ne"` + The ID of the container used to run the code. - - `"gt"` + - `outputs: array of object { logs, type } or object { type, url }` - - `"gte"` + The outputs generated by the code interpreter, such as logs or images. + Can be null if no outputs are available. - - `"lt"` + - `Logs object { logs, type }` - - `"lte"` + The logs output from the code interpreter. - - `"in"` + - `logs: string` - - `"nin"` + The logs output from the code interpreter. - - `value: string or number or boolean or array of string or number` + - `type: "logs"` - The value to compare against the attribute key; supports string, number, or boolean types. + The type of the output. Always `logs`. - - `string` + - `"logs"` - - `number` + - `Image object { type, url }` - - `boolean` + The image output from the code interpreter. - - `array of string or number` + - `type: "image"` - - `string` + The type of the output. Always `image`. - - `number` + - `"image"` - - `CompoundFilter object { filters, type }` + - `url: string` - Combine multiple filters using `and` or `or`. + The URL of the image output from the code interpreter. - - `filters: array of ComparisonFilter or unknown` + - `status: "in_progress" or "completed" or "incomplete" or 2 more` - Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. + The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. - - `ComparisonFilter object { key, type, value }` + - `"in_progress"` - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + - `"completed"` - - `unknown` + - `"incomplete"` - - `type: "and" or "or"` + - `"interpreting"` - Type of operation: `and` or `or`. + - `"failed"` - - `"and"` + - `type: "code_interpreter_call"` - - `"or"` + The type of the code interpreter tool call. Always `code_interpreter_call`. - - `max_num_results: optional number` + - `"code_interpreter_call"` - The maximum number of results to return. This number should be between 1 and 50 inclusive. + - `LocalShellCall object { id, action, call_id, 2 more }` - - `ranking_options: optional object { hybrid_search, ranker, score_threshold }` + A tool call to run a command on the local shell. - Ranking options for search. + - `id: string` - - `hybrid_search: optional object { embedding_weight, text_weight }` + The unique ID of the local shell call. - Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. + - `action: object { command, env, type, 3 more }` - - `embedding_weight: number` + Execute a shell command on the server. - The weight of the embedding in the reciprocal ranking fusion. + - `command: array of string` - - `text_weight: number` + The command to run. - The weight of the text in the reciprocal ranking fusion. + - `env: map[string]` - - `ranker: optional "auto" or "default-2024-11-15"` + Environment variables to set for the command. - The ranker to use for the file search. + - `type: "exec"` - - `"auto"` + The type of the local shell action. Always `exec`. - - `"default-2024-11-15"` + - `"exec"` - - `score_threshold: optional number` + - `timeout_ms: optional number` - The score threshold for the file search, a number between 0 and 1. Numbers closer to 1 will attempt to return only the most relevant results, but may return fewer results. + Optional timeout in milliseconds for the command. - - `Computer object { type }` + - `user: optional string` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + Optional user to run the command as. - - `type: "computer"` + - `working_directory: optional string` - The type of the computer tool. Always `computer`. + Optional working directory to run the command in. - - `"computer"` + - `call_id: string` - - `ComputerUsePreview object { display_height, display_width, environment, type }` + The unique ID of the local shell tool call generated by the model. - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `status: "in_progress" or "completed" or "incomplete"` - - `display_height: number` + The status of the local shell call. - The height of the computer display. + - `"in_progress"` - - `display_width: number` + - `"completed"` - The width of the computer display. + - `"incomplete"` - - `environment: "windows" or "mac" or "linux" or 2 more` + - `type: "local_shell_call"` - The type of computer environment to control. + The type of the local shell call. Always `local_shell_call`. - - `"windows"` + - `"local_shell_call"` - - `"mac"` + - `LocalShellCallOutput object { id, output, type, status }` - - `"linux"` + The output of a local shell tool call. - - `"ubuntu"` + - `id: string` - - `"browser"` + The unique ID of the local shell tool call generated by the model. - - `type: "computer_use_preview"` + - `output: string` - The type of the computer use tool. Always `computer_use_preview`. + A JSON string of the output of the local shell tool call. - - `"computer_use_preview"` + - `type: "local_shell_call_output"` - - `WebSearch object { type, filters, search_context_size, user_location }` + The type of the local shell tool call output. Always `local_shell_call_output`. - Search the Internet for sources related to the prompt. Learn more about the - [web search tool](/docs/guides/tools-web-search). + - `"local_shell_call_output"` - - `type: "web_search" or "web_search_2025_08_26"` + - `status: optional "in_progress" or "completed" or "incomplete"` - The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. + The status of the item. One of `in_progress`, `completed`, or `incomplete`. - - `"web_search"` + - `"in_progress"` - - `"web_search_2025_08_26"` + - `"completed"` - - `filters: optional object { allowed_domains }` + - `"incomplete"` - Filters for the search. + - `ShellCall object { id, action, call_id, 4 more }` - - `allowed_domains: optional array of string` + A tool call that executes one or more shell commands in a managed environment. - Allowed domains for the search. If not provided, all domains are allowed. - Subdomains of the provided domains are allowed as well. + - `id: string` - Example: `["pubmed.ncbi.nlm.nih.gov"]` + The unique ID of the shell tool call. Populated when this item is returned via API. - - `search_context_size: optional "low" or "medium" or "high"` + - `action: object { commands, max_output_length, timeout_ms }` - High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. + The shell commands and limits that describe how to run the tool call. - - `"low"` + - `commands: array of string` - - `"medium"` + - `max_output_length: number` - - `"high"` + Optional maximum number of characters to return from each command. - - `user_location: optional object { city, country, region, 2 more }` + - `timeout_ms: number` - The approximate location of the user. + Optional timeout in milliseconds for the commands. - - `city: optional string` + - `call_id: string` - Free text input for the city of the user, e.g. `San Francisco`. + The unique ID of the shell tool call generated by the model. - - `country: optional string` + - `environment: ResponseLocalEnvironment or ResponseContainerReference` - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + Represents the use of a local environment to perform shell actions. - - `region: optional string` + - `ResponseLocalEnvironment object { type }` - Free text input for the region of the user, e.g. `California`. + Represents the use of a local environment to perform shell actions. - - `timezone: optional string` + - `type: "local"` - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + The environment type. Always `local`. - - `type: optional "approximate"` + - `"local"` - The type of location approximation. Always `approximate`. + - `ResponseContainerReference object { container_id, type }` - - `"approximate"` + Represents a container created with /v1/containers. - - `Mcp object { server_label, type, allowed_tools, 7 more }` + - `container_id: string` - Give the model access to additional tools via remote Model Context Protocol - (MCP) servers. [Learn more about MCP](/docs/guides/tools-remote-mcp). + - `type: "container_reference"` - - `server_label: string` + The environment type. Always `container_reference`. - A label for this MCP server, used to identify it in tool calls. + - `"container_reference"` - - `type: "mcp"` + - `status: "in_progress" or "completed" or "incomplete"` - The type of the MCP tool. Always `mcp`. + The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. - - `"mcp"` + - `"in_progress"` - - `allowed_tools: optional array of string or object { read_only, tool_names }` + - `"completed"` - List of allowed tool names or a filter object. + - `"incomplete"` - - `McpAllowedTools = array of string` + - `type: "shell_call"` - A string array of allowed tool names + The type of the item. Always `shell_call`. - - `McpToolFilter object { read_only, tool_names }` + - `"shell_call"` - A filter object to specify which tools are allowed. + - `created_by: optional string` - - `read_only: optional boolean` + The ID of the entity that created this tool call. - Indicates whether or not a tool modifies data or is read-only. If an - MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), - it will match this filter. + - `ShellCallOutput object { id, call_id, max_output_length, 4 more }` - - `tool_names: optional array of string` + The output of a shell tool call that was emitted. - List of allowed tool names. + - `id: string` - - `authorization: optional string` + The unique ID of the shell call output. Populated when this item is returned via API. - An OAuth access token that can be used with a remote MCP server, either - with a custom MCP server URL or a service connector. Your application - must handle the OAuth authorization flow and provide the token here. + - `call_id: string` - - `connector_id: optional "connector_dropbox" or "connector_gmail" or "connector_googlecalendar" or 5 more` + The unique ID of the shell tool call generated by the model. - Identifier for service connectors, like those available in ChatGPT. One of - `server_url` or `connector_id` must be provided. Learn more about service - connectors [here](/docs/guides/tools-remote-mcp#connectors). + - `max_output_length: number` - Currently supported `connector_id` values are: + The maximum length of the shell command output. This is generated by the model and should be passed back with the raw output. - - Dropbox: `connector_dropbox` - - Gmail: `connector_gmail` - - Google Calendar: `connector_googlecalendar` - - Google Drive: `connector_googledrive` - - Microsoft Teams: `connector_microsoftteams` - - Outlook Calendar: `connector_outlookcalendar` - - Outlook Email: `connector_outlookemail` - - SharePoint: `connector_sharepoint` + - `output: array of object { outcome, stderr, stdout, created_by }` - - `"connector_dropbox"` + An array of shell call output contents - - `"connector_gmail"` + - `outcome: object { type } or object { exit_code, type }` - - `"connector_googlecalendar"` + Represents either an exit outcome (with an exit code) or a timeout outcome for a shell call output chunk. - - `"connector_googledrive"` + - `Timeout object { type }` - - `"connector_microsoftteams"` + Indicates that the shell call exceeded its configured time limit. - - `"connector_outlookcalendar"` + - `type: "timeout"` - - `"connector_outlookemail"` + The outcome type. Always `timeout`. - - `"connector_sharepoint"` + - `"timeout"` - - `defer_loading: optional boolean` + - `Exit object { exit_code, type }` - Whether this MCP tool is deferred and discovered via tool search. + Indicates that the shell commands finished and returned an exit code. - - `headers: optional map[string]` + - `exit_code: number` - Optional HTTP headers to send to the MCP server. Use for authentication - or other purposes. + Exit code from the shell process. - - `require_approval: optional object { always, never } or "always" or "never"` + - `type: "exit"` - Specify which of the MCP server's tools require approval. + The outcome type. Always `exit`. - - `McpToolApprovalFilter object { always, never }` + - `"exit"` - Specify which of the MCP server's tools require approval. Can be - `always`, `never`, or a filter object associated with tools - that require approval. + - `stderr: string` - - `always: optional object { read_only, tool_names }` + The standard error output that was captured. - A filter object to specify which tools are allowed. + - `stdout: string` - - `read_only: optional boolean` + The standard output that was captured. - Indicates whether or not a tool modifies data or is read-only. If an - MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), - it will match this filter. + - `created_by: optional string` - - `tool_names: optional array of string` + The identifier of the actor that created the item. - List of allowed tool names. + - `status: "in_progress" or "completed" or "incomplete"` - - `never: optional object { read_only, tool_names }` + The status of the shell call output. One of `in_progress`, `completed`, or `incomplete`. - A filter object to specify which tools are allowed. + - `"in_progress"` - - `read_only: optional boolean` + - `"completed"` - Indicates whether or not a tool modifies data or is read-only. If an - MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), - it will match this filter. + - `"incomplete"` - - `tool_names: optional array of string` + - `type: "shell_call_output"` - List of allowed tool names. + The type of the shell call output. Always `shell_call_output`. - - `McpToolApprovalSetting = "always" or "never"` + - `"shell_call_output"` - Specify a single approval policy for all tools. One of `always` or - `never`. When set to `always`, all tools will require approval. When - set to `never`, all tools will not require approval. + - `created_by: optional string` - - `"always"` + The identifier of the actor that created the item. - - `"never"` + - `ApplyPatchCall object { id, call_id, operation, 3 more }` - - `server_description: optional string` + A tool call that applies file diffs by creating, deleting, or updating files. - Optional description of the MCP server, used to provide more context. + - `id: string` - - `server_url: optional string` + The unique ID of the apply patch tool call. Populated when this item is returned via API. - The URL for the MCP server. One of `server_url` or `connector_id` must be - provided. + - `call_id: string` - - `CodeInterpreter object { container, type }` + The unique ID of the apply patch tool call generated by the model. - A tool that runs Python code to help generate a response to a prompt. + - `operation: object { diff, path, type } or object { path, type } or object { diff, path, type }` - - `container: string or object { type, file_ids, memory_limit, network_policy }` + One of the create_file, delete_file, or update_file operations applied via apply_patch. - The code interpreter container. Can be a container ID or an object that - specifies uploaded file IDs to make available to your code, along with an - optional `memory_limit` setting. + - `CreateFile object { diff, path, type }` - - `string` + Instruction describing how to create a file via the apply_patch tool. - The container ID. + - `diff: string` - - `CodeInterpreterToolAuto object { type, file_ids, memory_limit, network_policy }` + Diff to apply. - Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. + - `path: string` - - `type: "auto"` + Path of the file to create. - Always `auto`. + - `type: "create_file"` - - `"auto"` + Create a new file with the provided diff. - - `file_ids: optional array of string` + - `"create_file"` - An optional list of uploaded files to make available to your code. + - `DeleteFile object { path, type }` - - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` + Instruction describing how to delete a file via the apply_patch tool. - The memory limit for the code interpreter container. + - `path: string` - - `"1g"` + Path of the file to delete. - - `"4g"` + - `type: "delete_file"` - - `"16g"` + Delete the specified file. - - `"64g"` + - `"delete_file"` - - `network_policy: optional ContainerNetworkPolicyDisabled or ContainerNetworkPolicyAllowlist` + - `UpdateFile object { diff, path, type }` - Network access policy for the container. + Instruction describing how to update a file via the apply_patch tool. - - `ContainerNetworkPolicyDisabled object { type }` + - `diff: string` - - `type: "disabled"` + Diff to apply. - Disable outbound network access. Always `disabled`. + - `path: string` - - `"disabled"` + Path of the file to update. - - `ContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` + - `type: "update_file"` - - `allowed_domains: array of string` + Update an existing file with the provided diff. - A list of allowed domains when type is `allowlist`. + - `"update_file"` - - `type: "allowlist"` + - `status: "in_progress" or "completed"` - Allow outbound network access only to specified domains. Always `allowlist`. + The status of the apply patch tool call. One of `in_progress` or `completed`. - - `"allowlist"` + - `"in_progress"` - - `domain_secrets: optional array of ContainerNetworkPolicyDomainSecret` + - `"completed"` - Optional domain-scoped secrets for allowlisted domains. + - `type: "apply_patch_call"` - - `domain: string` + The type of the item. Always `apply_patch_call`. - The domain associated with the secret. + - `"apply_patch_call"` - - `name: string` + - `created_by: optional string` - The name of the secret to inject for the domain. + The ID of the entity that created this tool call. - - `value: string` + - `ApplyPatchCallOutput object { id, call_id, status, 3 more }` - The secret value to inject for the domain. + The output emitted by an apply patch tool call. - - `type: "code_interpreter"` + - `id: string` - The type of the code interpreter tool. Always `code_interpreter`. + The unique ID of the apply patch tool call output. Populated when this item is returned via API. - - `"code_interpreter"` + - `call_id: string` - - `ImageGeneration object { type, action, background, 9 more }` + The unique ID of the apply patch tool call generated by the model. - A tool that generates images using the GPT image models. + - `status: "completed" or "failed"` - - `type: "image_generation"` + The status of the apply patch tool call output. One of `completed` or `failed`. - The type of the image generation tool. Always `image_generation`. + - `"completed"` - - `"image_generation"` + - `"failed"` - - `action: optional "generate" or "edit" or "auto"` + - `type: "apply_patch_call_output"` - Whether to generate a new image or edit an existing image. Default: `auto`. + The type of the item. Always `apply_patch_call_output`. - - `"generate"` + - `"apply_patch_call_output"` - - `"edit"` + - `created_by: optional string` - - `"auto"` + The ID of the entity that created this tool call output. - - `background: optional "transparent" or "opaque" or "auto"` + - `output: optional string` - Background type for the generated image. One of `transparent`, - `opaque`, or `auto`. Default: `auto`. + Optional textual output returned by the apply patch tool. - - `"transparent"` + - `McpListTools object { id, server_label, tools, 2 more }` - - `"opaque"` + A list of tools available on an MCP server. - - `"auto"` + - `id: string` - - `input_fidelity: optional "high" or "low"` + The unique ID of the list. - Control how much effort the model will exert to match the style and features, especially facial features, of input images. This parameter is only supported for `gpt-image-1` and `gpt-image-1.5` and later models, unsupported for `gpt-image-1-mini`. Supports `high` and `low`. Defaults to `low`. + - `server_label: string` - - `"high"` + The label of the MCP server. - - `"low"` + - `tools: array of object { input_schema, name, annotations, description }` - - `input_image_mask: optional object { file_id, image_url }` + The tools available on the server. - Optional mask for inpainting. Contains `image_url` - (string, optional) and `file_id` (string, optional). + - `input_schema: unknown` - - `file_id: optional string` + The JSON schema describing the tool's input. - File ID for the mask image. + - `name: string` - - `image_url: optional string` + The name of the tool. - Base64-encoded mask image. + - `annotations: optional unknown` - - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` + Additional annotations about the tool. - The image generation model to use. Default: `gpt-image-1`. + - `description: optional string` - - `string` + The description of the tool. - - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` + - `type: "mcp_list_tools"` - The image generation model to use. Default: `gpt-image-1`. + The type of the item. Always `mcp_list_tools`. - - `"gpt-image-1"` + - `"mcp_list_tools"` - - `"gpt-image-1-mini"` + - `error: optional string` - - `"gpt-image-1.5"` + Error message if the server could not list tools. - - `moderation: optional "auto" or "low"` + - `McpApprovalRequest object { id, arguments, name, 2 more }` - Moderation level for the generated image. Default: `auto`. + A request for human approval of a tool invocation. - - `"auto"` + - `id: string` - - `"low"` + The unique ID of the approval request. - - `output_compression: optional number` + - `arguments: string` - Compression level for the output image. Default: 100. + A JSON string of arguments for the tool. - - `output_format: optional "png" or "webp" or "jpeg"` + - `name: string` - The output format of the generated image. One of `png`, `webp`, or - `jpeg`. Default: `png`. + The name of the tool to run. - - `"png"` + - `server_label: string` - - `"webp"` + The label of the MCP server making the request. - - `"jpeg"` + - `type: "mcp_approval_request"` - - `partial_images: optional number` + The type of the item. Always `mcp_approval_request`. - Number of partial images to generate in streaming mode, from 0 (default value) to 3. + - `"mcp_approval_request"` - - `quality: optional "low" or "medium" or "high" or "auto"` + - `McpApprovalResponse object { id, approval_request_id, approve, 2 more }` - The quality of the generated image. One of `low`, `medium`, `high`, - or `auto`. Default: `auto`. + A response to an MCP approval request. - - `"low"` + - `id: string` - - `"medium"` + The unique ID of the approval response - - `"high"` + - `approval_request_id: string` - - `"auto"` + The ID of the approval request being answered. - - `size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or "auto"` + - `approve: boolean` - The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. + Whether the request was approved. - - `string` + - `type: "mcp_approval_response"` - - `"1024x1024" or "1024x1536" or "1536x1024" or "auto"` + The type of the item. Always `mcp_approval_response`. - The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. + - `"mcp_approval_response"` - - `"1024x1024"` + - `reason: optional string` - - `"1024x1536"` + Optional reason for the decision. - - `"1536x1024"` + - `McpCall object { id, arguments, name, 6 more }` - - `"auto"` + An invocation of a tool on an MCP server. - - `LocalShell object { type }` + - `id: string` - A tool that allows the model to execute shell commands in a local environment. + The unique ID of the tool call. - - `type: "local_shell"` + - `arguments: string` - The type of the local shell tool. Always `local_shell`. + A JSON string of the arguments passed to the tool. - - `"local_shell"` + - `name: string` - - `Shell object { type, environment }` + The name of the tool that was run. - A tool that allows the model to execute shell commands. + - `server_label: string` - - `type: "shell"` + The label of the MCP server running the tool. - The type of the shell tool. Always `shell`. + - `type: "mcp_call"` - - `"shell"` + The type of the item. Always `mcp_call`. - - `environment: optional ContainerAuto or LocalEnvironment or ContainerReference` + - `"mcp_call"` - - `ContainerAuto object { type, file_ids, memory_limit, 2 more }` + - `approval_request_id: optional string` - - `type: "container_auto"` + Unique identifier for the MCP tool call approval request. + Include this value in a subsequent `mcp_approval_response` input to approve or reject the corresponding tool call. - Automatically creates a container for this request + - `error: optional string` - - `"container_auto"` + The error from the tool call, if any. - - `file_ids: optional array of string` + - `output: optional string` - An optional list of uploaded files to make available to your code. + The output from the tool call. - - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` + - `status: optional "in_progress" or "completed" or "incomplete" or 2 more` - The memory limit for the container. + The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. - - `"1g"` + - `"in_progress"` - - `"4g"` + - `"completed"` - - `"16g"` + - `"incomplete"` - - `"64g"` + - `"calling"` - - `network_policy: optional ContainerNetworkPolicyDisabled or ContainerNetworkPolicyAllowlist` + - `"failed"` - Network access policy for the container. + - `CustomToolCall object { call_id, input, name, 3 more }` - - `ContainerNetworkPolicyDisabled object { type }` + A call to a custom tool created by the model. - - `ContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` + - `call_id: string` - - `skills: optional array of SkillReference or InlineSkill` + An identifier used to map this custom tool call to a tool call output. - An optional list of skills referenced by id or inline data. + - `input: string` - - `SkillReference object { skill_id, type, version }` + The input for the custom tool call generated by the model. - - `skill_id: string` + - `name: string` - The ID of the referenced skill. + The name of the custom tool being called. - - `type: "skill_reference"` + - `type: "custom_tool_call"` - References a skill created with the /v1/skills endpoint. + The type of the custom tool call. Always `custom_tool_call`. - - `"skill_reference"` + - `"custom_tool_call"` - - `version: optional string` + - `id: optional string` - Optional skill version. Use a positive integer or 'latest'. Omit for default. + The unique ID of the custom tool call in the OpenAI platform. - - `InlineSkill object { description, name, source, type }` + - `namespace: optional string` - - `description: string` + The namespace of the custom tool being called. - The description of the skill. + - `CustomToolCallOutput object { call_id, output, type, id }` - - `name: string` + The output of a custom tool call from your code, being sent back to the model. - The name of the skill. + - `call_id: string` - - `source: InlineSkillSource` + The call ID, used to map this custom tool call output to a custom tool call. - Inline skill payload + - `output: string or array of ResponseInputText or ResponseInputImage or ResponseInputFile` - - `data: string` + The output from the custom tool call generated by your code. + Can be a string or an list of output content. - Base64-encoded skill zip bundle. + - `StringOutput = string` - - `media_type: "application/zip"` + A string of the output of the custom tool call. - The media type of the inline skill payload. Must be `application/zip`. + - `OutputContentList = array of ResponseInputText or ResponseInputImage or ResponseInputFile` - - `"application/zip"` + Text, image, or file output of the custom tool call. - - `type: "base64"` + - `ResponseInputText object { text, type }` - The type of the inline skill source. Must be `base64`. + A text input to the model. - - `"base64"` + - `ResponseInputImage object { detail, type, file_id, image_url }` - - `type: "inline"` + An image input to the model. Learn about [image inputs](/docs/guides/vision). - Defines an inline skill for this request. + - `ResponseInputFile object { type, detail, file_data, 3 more }` - - `"inline"` + A file input to the model. - - `LocalEnvironment object { type, skills }` + - `type: "custom_tool_call_output"` - - `type: "local"` + The type of the custom tool call output. Always `custom_tool_call_output`. - Use a local computer environment. + - `"custom_tool_call_output"` - - `"local"` + - `id: optional string` - - `skills: optional array of LocalSkill` + The unique ID of the custom tool call output in the OpenAI platform. - An optional list of skills. +### Conversation Item List - - `description: string` +- `ConversationItemList object { data, first_id, has_more, 2 more }` - The description of the skill. + A list of Conversation items. - - `name: string` + - `data: array of ConversationItem` - The name of the skill. + A list of conversation items. - - `path: string` + - `Message object { id, content, role, 3 more }` - The path to the directory containing the skill. + A message to or from the model. - - `ContainerReference object { container_id, type }` + - `id: string` - - `container_id: string` + The unique ID of the message. - The ID of the referenced container. + - `content: array of ResponseInputText or ResponseOutputText or TextContent or 6 more` - - `type: "container_reference"` + The content of the message - References a container created with the /v1/containers endpoint + - `ResponseInputText object { text, type }` - - `"container_reference"` + A text input to the model. - - `Custom object { name, type, defer_loading, 2 more }` + - `text: string` - A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) + The text input to the model. - - `name: string` + - `type: "input_text"` - The name of the custom tool, used to identify it in tool calls. + The type of the input item. Always `input_text`. - - `type: "custom"` + - `"input_text"` - The type of the custom tool. Always `custom`. + - `ResponseOutputText object { annotations, logprobs, text, type }` - - `"custom"` + A text output from the model. - - `defer_loading: optional boolean` + - `annotations: array of object { file_id, filename, index, type } or object { end_index, start_index, title, 2 more } or object { container_id, end_index, file_id, 3 more } or object { file_id, index, type }` - Whether this tool should be deferred and discovered via tool search. + The annotations of the text output. - - `description: optional string` + - `FileCitation object { file_id, filename, index, type }` - Optional description of the custom tool, used to provide more context. + A citation to a file. - - `format: optional CustomToolInputFormat` + - `file_id: string` - The input format for the custom tool. Default is unconstrained text. + The ID of the file. - - `Text object { type }` + - `filename: string` - Unconstrained free-form text. + The filename of the file cited. - - `type: "text"` + - `index: number` - Unconstrained text format. Always `text`. + The index of the file in the list of files. - - `"text"` + - `type: "file_citation"` - - `Grammar object { definition, syntax, type }` + The type of the file citation. Always `file_citation`. - A grammar defined by the user. + - `"file_citation"` - - `definition: string` + - `URLCitation object { end_index, start_index, title, 2 more }` - The grammar definition. + A citation for a web resource used to generate a model response. - - `syntax: "lark" or "regex"` + - `end_index: number` - The syntax of the grammar definition. One of `lark` or `regex`. + The index of the last character of the URL citation in the message. - - `"lark"` + - `start_index: number` - - `"regex"` + The index of the first character of the URL citation in the message. - - `type: "grammar"` + - `title: string` - Grammar format. Always `grammar`. + The title of the web resource. - - `"grammar"` + - `type: "url_citation"` - - `Namespace object { description, name, tools, type }` + The type of the URL citation. Always `url_citation`. - Groups function/custom tools under a shared namespace. + - `"url_citation"` - - `description: string` + - `url: string` - A description of the namespace shown to the model. + The URL of the web resource. - - `name: string` + - `ContainerFileCitation object { container_id, end_index, file_id, 3 more }` - The namespace name used in tool calls (for example, `crm`). + A citation for a container file used to generate a model response. - - `tools: array of object { name, type, defer_loading, 3 more } or object { name, type, defer_loading, 2 more }` + - `container_id: string` - The function/custom tools available inside this namespace. + The ID of the container file. - - `Function object { name, type, defer_loading, 3 more }` + - `end_index: number` - - `name: string` + The index of the last character of the container file citation in the message. - - `type: "function"` + - `file_id: string` - - `"function"` + The ID of the file. - - `defer_loading: optional boolean` + - `filename: string` - Whether this function should be deferred and discovered via tool search. + The filename of the container file cited. - - `description: optional string` + - `start_index: number` - - `parameters: optional unknown` + The index of the first character of the container file citation in the message. - - `strict: optional boolean` + - `type: "container_file_citation"` - - `Custom object { name, type, defer_loading, 2 more }` + The type of the container file citation. Always `container_file_citation`. - A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) + - `"container_file_citation"` - - `name: string` + - `FilePath object { file_id, index, type }` - The name of the custom tool, used to identify it in tool calls. + A path to a file. - - `type: "custom"` + - `file_id: string` - The type of the custom tool. Always `custom`. + The ID of the file. - - `"custom"` + - `index: number` - - `defer_loading: optional boolean` + The index of the file in the list of files. - Whether this tool should be deferred and discovered via tool search. + - `type: "file_path"` - - `description: optional string` + The type of the file path. Always `file_path`. - Optional description of the custom tool, used to provide more context. + - `"file_path"` - - `format: optional CustomToolInputFormat` + - `logprobs: array of object { token, bytes, logprob, top_logprobs }` - The input format for the custom tool. Default is unconstrained text. + - `token: string` - - `type: "namespace"` + - `bytes: array of number` - The type of the tool. Always `namespace`. + - `logprob: number` - - `"namespace"` + - `top_logprobs: array of object { token, bytes, logprob }` - - `ToolSearch object { type, description, execution, parameters }` + - `token: string` - Hosted or BYOT tool search configuration for deferred tools. + - `bytes: array of number` - - `type: "tool_search"` + - `logprob: number` - The type of the tool. Always `tool_search`. + - `text: string` - - `"tool_search"` + The text output from the model. - - `description: optional string` + - `type: "output_text"` - Description shown to the model for a client-executed tool search tool. + The type of the output text. Always `output_text`. - - `execution: optional "server" or "client"` + - `"output_text"` - Whether tool search is executed by the server or by the client. + - `TextContent object { text, type }` - - `"server"` + A text content. - - `"client"` + - `text: string` - - `parameters: optional unknown` + - `type: "text"` - Parameter schema for a client-executed tool search tool. + - `"text"` - - `WebSearchPreview object { type, search_content_types, search_context_size, user_location }` + - `SummaryTextContent object { text, type }` - This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + A summary text from the model. - - `type: "web_search_preview" or "web_search_preview_2025_03_11"` + - `text: string` - The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. + A summary of the reasoning output from the model so far. - - `"web_search_preview"` + - `type: "summary_text"` - - `"web_search_preview_2025_03_11"` + The type of the object. Always `summary_text`. - - `search_content_types: optional array of "text" or "image"` + - `"summary_text"` - - `"text"` + - `ReasoningText object { text, type }` - - `"image"` + Reasoning text from the model. - - `search_context_size: optional "low" or "medium" or "high"` + - `text: string` - High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. + The reasoning text from the model. - - `"low"` + - `type: "reasoning_text"` - - `"medium"` + The type of the reasoning text. Always `reasoning_text`. - - `"high"` + - `"reasoning_text"` - - `user_location: optional object { type, city, country, 2 more }` + - `ResponseOutputRefusal object { refusal, type }` - The user's location. + A refusal from the model. - - `type: "approximate"` + - `refusal: string` - The type of location approximation. Always `approximate`. + The refusal explanation from the model. - - `"approximate"` + - `type: "refusal"` - - `city: optional string` + The type of the refusal. Always `refusal`. - Free text input for the city of the user, e.g. `San Francisco`. + - `"refusal"` - - `country: optional string` + - `ResponseInputImage object { detail, type, file_id, image_url }` - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + An image input to the model. Learn about [image inputs](/docs/guides/vision). - - `region: optional string` + - `detail: "low" or "high" or "auto" or "original"` - Free text input for the region of the user, e.g. `California`. + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - - `timezone: optional string` + - `"low"` - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + - `"high"` - - `ApplyPatch object { type }` + - `"auto"` - Allows the assistant to create, delete, or update files using unified diffs. + - `"original"` - - `type: "apply_patch"` + - `type: "input_image"` - The type of the tool. Always `apply_patch`. + The type of the input item. Always `input_image`. - - `"apply_patch"` + - `"input_image"` - - `type: "tool_search_output"` + - `file_id: optional string` - The type of the item. Always `tool_search_output`. + The ID of the file to be sent to the model. - - `"tool_search_output"` + - `image_url: optional string` - - `created_by: optional string` + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - The identifier of the actor that created the item. + - `ComputerScreenshotContent object { detail, file_id, image_url, type }` - - `Reasoning object { id, summary, type, 3 more }` + A screenshot of a computer. - 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). + - `detail: "low" or "high" or "auto" or "original"` - - `id: string` + The detail level of the screenshot image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - The unique identifier of the reasoning content. + - `"low"` - - `summary: array of SummaryTextContent` + - `"high"` - Reasoning summary content. + - `"auto"` - - `text: string` + - `"original"` - A summary of the reasoning output from the model so far. + - `file_id: string` - - `type: "summary_text"` + The identifier of an uploaded file that contains the screenshot. - The type of the object. Always `summary_text`. + - `image_url: string` - - `type: "reasoning"` + The URL of the screenshot image. - The type of the object. Always `reasoning`. + - `type: "computer_screenshot"` - - `"reasoning"` + Specifies the event type. For a computer screenshot, this property is always set to `computer_screenshot`. - - `content: optional array of object { text, type }` + - `"computer_screenshot"` - Reasoning text content. + - `ResponseInputFile object { type, detail, file_data, 3 more }` - - `text: string` + A file input to the model. - The reasoning text from the model. + - `type: "input_file"` - - `type: "reasoning_text"` + The type of the input item. Always `input_file`. - The type of the reasoning text. Always `reasoning_text`. + - `"input_file"` - - `"reasoning_text"` + - `detail: optional "low" or "high"` - - `encrypted_content: optional string` + 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 encrypted content of the reasoning item - populated when a response is - generated with `reasoning.encrypted_content` in the `include` parameter. + - `"low"` - - `status: optional "in_progress" or "completed" or "incomplete"` + - `"high"` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `file_data: optional string` - - `"in_progress"` + The content of the file to be sent to the model. - - `"completed"` + - `file_id: optional string` - - `"incomplete"` + The ID of the file to be sent to the model. - - `Compaction object { id, encrypted_content, type, created_by }` + - `file_url: optional string` - A compaction item generated by the [`v1/responses/compact` API](/docs/api-reference/responses/compact). + The URL of the file to be sent to the model. - - `id: string` + - `filename: optional string` - The unique ID of the compaction item. + The name of the file to be sent to the model. - - `encrypted_content: string` + - `role: "unknown" or "user" or "assistant" or 5 more` - The encrypted content that was produced by compaction. + The role of the message. One of `unknown`, `user`, `assistant`, `system`, `critic`, `discriminator`, `developer`, or `tool`. - - `type: "compaction"` + - `"unknown"` - The type of the item. Always `compaction`. + - `"user"` - - `"compaction"` + - `"assistant"` - - `created_by: optional string` + - `"system"` - The identifier of the actor that created the item. + - `"critic"` - - `CodeInterpreterCall object { id, code, container_id, 3 more }` + - `"discriminator"` - A tool call to run code. + - `"developer"` - - `id: string` + - `"tool"` - The unique ID of the code interpreter tool call. + - `status: "in_progress" or "completed" or "incomplete"` - - `code: string` + The status of item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. - The code to run, or null if not available. + - `"in_progress"` - - `container_id: string` + - `"completed"` - The ID of the container used to run the code. + - `"incomplete"` - - `outputs: array of object { logs, type } or object { type, url }` + - `type: "message"` - The outputs generated by the code interpreter, such as logs or images. - Can be null if no outputs are available. + The type of the message. Always set to `message`. - - `Logs object { logs, type }` + - `"message"` - The logs output from the code interpreter. + - `phase: optional "commentary" or "final_answer"` - - `logs: string` + Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend phase on all assistant messages — dropping it can degrade performance. Not used for user messages. - The logs output from the code interpreter. + - `"commentary"` - - `type: "logs"` + - `"final_answer"` - The type of the output. Always `logs`. + - `FunctionCall object { id, arguments, call_id, 5 more }` - - `"logs"` + - `id: string` - - `Image object { type, url }` + The unique ID of the function tool call. - The image output from the code interpreter. + - `arguments: string` - - `type: "image"` + A JSON string of the arguments to pass to the function. - The type of the output. Always `image`. + - `call_id: string` - - `"image"` + The unique ID of the function tool call generated by the model. - - `url: string` + - `name: string` - The URL of the image output from the code interpreter. + The name of the function to run. - - `status: "in_progress" or "completed" or "incomplete" or 2 more` + - `status: "in_progress" or "completed" or "incomplete"` - The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - `"in_progress"` @@ -17377,61 +22868,59 @@ curl -X DELETE https://api.openai.com/v1/conversations/conv_123/items/msg_abc \ - `"incomplete"` - - `"interpreting"` - - - `"failed"` - - - `type: "code_interpreter_call"` + - `type: "function_call"` - The type of the code interpreter tool call. Always `code_interpreter_call`. + The type of the function tool call. Always `function_call`. - - `"code_interpreter_call"` + - `"function_call"` - - `LocalShellCall object { id, action, call_id, 2 more }` + - `created_by: optional string` - A tool call to run a command on the local shell. + The identifier of the actor that created the item. - - `id: string` + - `namespace: optional string` - The unique ID of the local shell call. + The namespace of the function to run. - - `action: object { command, env, type, 3 more }` + - `FunctionCallOutput object { id, call_id, output, 3 more }` - Execute a shell command on the server. + - `id: string` - - `command: array of string` + The unique ID of the function call tool output. - The command to run. + - `call_id: string` - - `env: map[string]` + The unique ID of the function tool call generated by the model. - Environment variables to set for the command. + - `output: string or array of ResponseInputText or ResponseInputImage or ResponseInputFile` - - `type: "exec"` + The output from the function call generated by your code. + Can be a string or an list of output content. - The type of the local shell action. Always `exec`. + - `StringOutput = string` - - `"exec"` + A string of the output of the function call. - - `timeout_ms: optional number` + - `OutputContentList = array of ResponseInputText or ResponseInputImage or ResponseInputFile` - Optional timeout in milliseconds for the command. + Text, image, or file output of the function call. - - `user: optional string` + - `ResponseInputText object { text, type }` - Optional user to run the command as. + A text input to the model. - - `working_directory: optional string` + - `ResponseInputImage object { detail, type, file_id, image_url }` - Optional working directory to run the command in. + An image input to the model. Learn about [image inputs](/docs/guides/vision). - - `call_id: string` + - `ResponseInputFile object { type, detail, file_data, 3 more }` - The unique ID of the local shell tool call generated by the model. + A file input to the model. - `status: "in_progress" or "completed" or "incomplete"` - The status of the local shell call. + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - `"in_progress"` @@ -17439,1603 +22928,1645 @@ curl -X DELETE https://api.openai.com/v1/conversations/conv_123/items/msg_abc \ - `"incomplete"` - - `type: "local_shell_call"` - - The type of the local shell call. Always `local_shell_call`. + - `type: "function_call_output"` - - `"local_shell_call"` + The type of the function tool call output. Always `function_call_output`. - - `LocalShellCallOutput object { id, output, type, status }` + - `"function_call_output"` - The output of a local shell tool call. + - `created_by: optional string` - - `id: string` + The identifier of the actor that created the item. - The unique ID of the local shell tool call generated by the model. + - `FileSearchCall object { id, queries, status, 2 more }` - - `output: string` + The results of a file search tool call. See the + [file search guide](/docs/guides/tools-file-search) for more information. - A JSON string of the output of the local shell tool call. + - `id: string` - - `type: "local_shell_call_output"` + The unique ID of the file search tool call. - The type of the local shell tool call output. Always `local_shell_call_output`. + - `queries: array of string` - - `"local_shell_call_output"` + The queries used to search for files. - - `status: optional "in_progress" or "completed" or "incomplete"` + - `status: "in_progress" or "searching" or "completed" or 2 more` - The status of the item. One of `in_progress`, `completed`, or `incomplete`. + The status of the file search tool call. One of `in_progress`, + `searching`, `incomplete` or `failed`, - `"in_progress"` + - `"searching"` + - `"completed"` - `"incomplete"` - - `ShellCall object { id, action, call_id, 4 more }` + - `"failed"` - A tool call that executes one or more shell commands in a managed environment. + - `type: "file_search_call"` - - `id: string` + The type of the file search tool call. Always `file_search_call`. - The unique ID of the shell tool call. Populated when this item is returned via API. + - `"file_search_call"` - - `action: object { commands, max_output_length, timeout_ms }` + - `results: optional array of object { attributes, file_id, filename, 2 more }` - The shell commands and limits that describe how to run the tool call. + The results of the file search tool call. - - `commands: array of string` + - `attributes: optional map[string or number or boolean]` - - `max_output_length: number` + Set of 16 key-value pairs that can be attached to an object. This can be + useful for storing additional information about the object in a structured + format, and querying for objects via API or the dashboard. Keys are strings + with a maximum length of 64 characters. Values are strings with a maximum + length of 512 characters, booleans, or numbers. - Optional maximum number of characters to return from each command. + - `string` - - `timeout_ms: number` + - `number` - Optional timeout in milliseconds for the commands. + - `boolean` - - `call_id: string` + - `file_id: optional string` - The unique ID of the shell tool call generated by the model. + The unique ID of the file. - - `environment: ResponseLocalEnvironment or ResponseContainerReference` + - `filename: optional string` - Represents the use of a local environment to perform shell actions. + The name of the file. - - `ResponseLocalEnvironment object { type }` + - `score: optional number` - Represents the use of a local environment to perform shell actions. + The relevance score of the file - a value between 0 and 1. - - `type: "local"` + - `text: optional string` - The environment type. Always `local`. + The text that was retrieved from the file. - - `"local"` + - `WebSearchCall object { id, action, status, type }` - - `ResponseContainerReference object { container_id, type }` + The results of a web search tool call. See the + [web search guide](/docs/guides/tools-web-search) for more information. - Represents a container created with /v1/containers. + - `id: string` - - `container_id: string` + The unique ID of the web search tool call. - - `type: "container_reference"` + - `action: object { type, queries, query, sources } or object { type, url } or object { pattern, type, url }` - The environment type. Always `container_reference`. + An object describing the specific action taken in this web search call. + Includes details on how the model used the web (search, open_page, find_in_page). - - `"container_reference"` + - `Search object { type, queries, query, sources }` + + Action type "search" - Performs a web search query. + + - `type: "search"` + + The action type. + + - `"search"` + + - `queries: optional array of string` + + The search queries. - - `status: "in_progress" or "completed" or "incomplete"` + - `query: optional string` - The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. + The search query. - - `"in_progress"` + - `sources: optional array of object { type, url }` - - `"completed"` + The sources used in the search. - - `"incomplete"` + - `type: "url"` - - `type: "shell_call"` + The type of source. Always `url`. - The type of the item. Always `shell_call`. + - `"url"` - - `"shell_call"` + - `url: string` - - `created_by: optional string` + The URL of the source. - The ID of the entity that created this tool call. + - `OpenPage object { type, url }` - - `ShellCallOutput object { id, call_id, max_output_length, 4 more }` + Action type "open_page" - Opens a specific URL from search results. - The output of a shell tool call that was emitted. + - `type: "open_page"` - - `id: string` + The action type. - The unique ID of the shell call output. Populated when this item is returned via API. + - `"open_page"` - - `call_id: string` + - `url: optional string` - The unique ID of the shell tool call generated by the model. + The URL opened by the model. - - `max_output_length: number` + - `FindInPage object { pattern, type, url }` - The maximum length of the shell command output. This is generated by the model and should be passed back with the raw output. + Action type "find_in_page": Searches for a pattern within a loaded page. - - `output: array of object { outcome, stderr, stdout, created_by }` + - `pattern: string` - An array of shell call output contents + The pattern or text to search for within the page. - - `outcome: object { type } or object { exit_code, type }` + - `type: "find_in_page"` - Represents either an exit outcome (with an exit code) or a timeout outcome for a shell call output chunk. + The action type. - - `Timeout object { type }` + - `"find_in_page"` - Indicates that the shell call exceeded its configured time limit. + - `url: string` - - `type: "timeout"` + The URL of the page searched for the pattern. - The outcome type. Always `timeout`. + - `status: "in_progress" or "searching" or "completed" or "failed"` - - `"timeout"` + The status of the web search tool call. - - `Exit object { exit_code, type }` + - `"in_progress"` - Indicates that the shell commands finished and returned an exit code. + - `"searching"` - - `exit_code: number` + - `"completed"` - Exit code from the shell process. + - `"failed"` - - `type: "exit"` + - `type: "web_search_call"` - The outcome type. Always `exit`. + The type of the web search tool call. Always `web_search_call`. - - `"exit"` + - `"web_search_call"` - - `stderr: string` + - `ImageGenerationCall object { id, result, status, type }` - The standard error output that was captured. + An image generation request made by the model. - - `stdout: string` + - `id: string` - The standard output that was captured. + The unique ID of the image generation call. - - `created_by: optional string` + - `result: string` - The identifier of the actor that created the item. + The generated image encoded in base64. - - `status: "in_progress" or "completed" or "incomplete"` + - `status: "in_progress" or "completed" or "generating" or "failed"` - The status of the shell call output. One of `in_progress`, `completed`, or `incomplete`. + The status of the image generation call. - `"in_progress"` - `"completed"` - - `"incomplete"` - - - `type: "shell_call_output"` + - `"generating"` - The type of the shell call output. Always `shell_call_output`. + - `"failed"` - - `"shell_call_output"` + - `type: "image_generation_call"` - - `created_by: optional string` + The type of the image generation call. Always `image_generation_call`. - The identifier of the actor that created the item. + - `"image_generation_call"` - - `ApplyPatchCall object { id, call_id, operation, 3 more }` + - `ComputerCall object { id, call_id, pending_safety_checks, 4 more }` - A tool call that applies file diffs by creating, deleting, or updating files. + A tool call to a computer use tool. See the + [computer use guide](/docs/guides/tools-computer-use) for more information. - `id: string` - The unique ID of the apply patch tool call. Populated when this item is returned via API. + The unique ID of the computer call. - `call_id: string` - The unique ID of the apply patch tool call generated by the model. + An identifier used when responding to the tool call with output. - - `operation: object { diff, path, type } or object { path, type } or object { diff, path, type }` + - `pending_safety_checks: array of object { id, code, message }` - One of the create_file, delete_file, or update_file operations applied via apply_patch. + The pending safety checks for the computer call. - - `CreateFile object { diff, path, type }` + - `id: string` - Instruction describing how to create a file via the apply_patch tool. + The ID of the pending safety check. - - `diff: string` + - `code: optional string` - Diff to apply. + The type of the pending safety check. - - `path: string` + - `message: optional string` - Path of the file to create. + Details about the pending safety check. - - `type: "create_file"` + - `status: "in_progress" or "completed" or "incomplete"` - Create a new file with the provided diff. + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `"create_file"` + - `"in_progress"` - - `DeleteFile object { path, type }` + - `"completed"` - Instruction describing how to delete a file via the apply_patch tool. + - `"incomplete"` - - `path: string` + - `type: "computer_call"` - Path of the file to delete. + The type of the computer call. Always `computer_call`. - - `type: "delete_file"` + - `"computer_call"` - Delete the specified file. + - `action: optional ComputerAction` - - `"delete_file"` + A click action. - - `UpdateFile object { diff, path, type }` + - `Click object { button, type, x, 2 more }` - Instruction describing how to update a file via the apply_patch tool. + A click action. - - `diff: string` + - `button: "left" or "right" or "wheel" or 2 more` - Diff to apply. + Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. - - `path: string` + - `"left"` - Path of the file to update. + - `"right"` - - `type: "update_file"` + - `"wheel"` - Update an existing file with the provided diff. + - `"back"` - - `"update_file"` + - `"forward"` - - `status: "in_progress" or "completed"` + - `type: "click"` - The status of the apply patch tool call. One of `in_progress` or `completed`. + Specifies the event type. For a click action, this property is always `click`. - - `"in_progress"` + - `"click"` - - `"completed"` + - `x: number` - - `type: "apply_patch_call"` + The x-coordinate where the click occurred. - The type of the item. Always `apply_patch_call`. + - `y: number` - - `"apply_patch_call"` + The y-coordinate where the click occurred. - - `created_by: optional string` + - `keys: optional array of string` - The ID of the entity that created this tool call. + The keys being held while clicking. - - `ApplyPatchCallOutput object { id, call_id, status, 3 more }` + - `DoubleClick object { keys, type, x, y }` - The output emitted by an apply patch tool call. + A double click action. - - `id: string` + - `keys: array of string` - The unique ID of the apply patch tool call output. Populated when this item is returned via API. + The keys being held while double-clicking. - - `call_id: string` + - `type: "double_click"` - The unique ID of the apply patch tool call generated by the model. + Specifies the event type. For a double click action, this property is always set to `double_click`. - - `status: "completed" or "failed"` + - `"double_click"` - The status of the apply patch tool call output. One of `completed` or `failed`. + - `x: number` - - `"completed"` + The x-coordinate where the double click occurred. - - `"failed"` + - `y: number` - - `type: "apply_patch_call_output"` + The y-coordinate where the double click occurred. - The type of the item. Always `apply_patch_call_output`. + - `Drag object { path, type, keys }` - - `"apply_patch_call_output"` + A drag action. - - `created_by: optional string` + - `path: array of object { x, y }` - The ID of the entity that created this tool call output. + An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg - - `output: optional string` + ``` + [ + { x: 100, y: 200 }, + { x: 200, y: 300 } + ] + ``` - Optional textual output returned by the apply patch tool. + - `x: number` - - `McpListTools object { id, server_label, tools, 2 more }` + The x-coordinate. - A list of tools available on an MCP server. + - `y: number` - - `id: string` + The y-coordinate. - The unique ID of the list. + - `type: "drag"` - - `server_label: string` + Specifies the event type. For a drag action, this property is always set to `drag`. - The label of the MCP server. + - `"drag"` - - `tools: array of object { input_schema, name, annotations, description }` + - `keys: optional array of string` - The tools available on the server. + The keys being held while dragging the mouse. - - `input_schema: unknown` + - `Keypress object { keys, type }` - The JSON schema describing the tool's input. + A collection of keypresses the model would like to perform. - - `name: string` + - `keys: array of string` - The name of the tool. + The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. - - `annotations: optional unknown` + - `type: "keypress"` - Additional annotations about the tool. + Specifies the event type. For a keypress action, this property is always set to `keypress`. - - `description: optional string` + - `"keypress"` - The description of the tool. + - `Move object { type, x, y, keys }` - - `type: "mcp_list_tools"` + A mouse move action. - The type of the item. Always `mcp_list_tools`. + - `type: "move"` - - `"mcp_list_tools"` + Specifies the event type. For a move action, this property is always set to `move`. - - `error: optional string` + - `"move"` + + - `x: number` - Error message if the server could not list tools. + The x-coordinate to move to. - - `McpApprovalRequest object { id, arguments, name, 2 more }` + - `y: number` - A request for human approval of a tool invocation. + The y-coordinate to move to. - - `id: string` + - `keys: optional array of string` - The unique ID of the approval request. + The keys being held while moving the mouse. - - `arguments: string` + - `Screenshot object { type }` - A JSON string of arguments for the tool. + A screenshot action. - - `name: string` + - `type: "screenshot"` - The name of the tool to run. + Specifies the event type. For a screenshot action, this property is always set to `screenshot`. - - `server_label: string` + - `"screenshot"` - The label of the MCP server making the request. + - `Scroll object { scroll_x, scroll_y, type, 3 more }` - - `type: "mcp_approval_request"` + A scroll action. - The type of the item. Always `mcp_approval_request`. + - `scroll_x: number` - - `"mcp_approval_request"` + The horizontal scroll distance. - - `McpApprovalResponse object { id, approval_request_id, approve, 2 more }` + - `scroll_y: number` - A response to an MCP approval request. + The vertical scroll distance. - - `id: string` + - `type: "scroll"` - The unique ID of the approval response + Specifies the event type. For a scroll action, this property is always set to `scroll`. - - `approval_request_id: string` + - `"scroll"` - The ID of the approval request being answered. + - `x: number` - - `approve: boolean` + The x-coordinate where the scroll occurred. - Whether the request was approved. + - `y: number` - - `type: "mcp_approval_response"` + The y-coordinate where the scroll occurred. - The type of the item. Always `mcp_approval_response`. + - `keys: optional array of string` - - `"mcp_approval_response"` + The keys being held while scrolling. - - `reason: optional string` + - `Type object { text, type }` - Optional reason for the decision. + An action to type in text. - - `McpCall object { id, arguments, name, 6 more }` + - `text: string` - An invocation of a tool on an MCP server. + The text to type. - - `id: string` + - `type: "type"` - The unique ID of the tool call. + Specifies the event type. For a type action, this property is always set to `type`. - - `arguments: string` + - `"type"` - A JSON string of the arguments passed to the tool. + - `Wait object { type }` - - `name: string` + A wait action. - The name of the tool that was run. + - `type: "wait"` - - `server_label: string` + Specifies the event type. For a wait action, this property is always set to `wait`. - The label of the MCP server running the tool. + - `"wait"` - - `type: "mcp_call"` + - `actions: optional ComputerActionList` - The type of the item. Always `mcp_call`. + Flattened batched actions for `computer_use`. Each action includes an + `type` discriminator and action-specific fields. - - `"mcp_call"` + - `Click object { button, type, x, 2 more }` - - `approval_request_id: optional string` + A click action. - Unique identifier for the MCP tool call approval request. - Include this value in a subsequent `mcp_approval_response` input to approve or reject the corresponding tool call. + - `DoubleClick object { keys, type, x, y }` - - `error: optional string` + A double click action. - The error from the tool call, if any. + - `Drag object { path, type, keys }` - - `output: optional string` + A drag action. - The output from the tool call. + - `Keypress object { keys, type }` - - `status: optional "in_progress" or "completed" or "incomplete" or 2 more` + A collection of keypresses the model would like to perform. - The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. + - `Move object { type, x, y, keys }` - - `"in_progress"` + A mouse move action. - - `"completed"` + - `Screenshot object { type }` - - `"incomplete"` + A screenshot action. - - `"calling"` + - `Scroll object { scroll_x, scroll_y, type, 3 more }` - - `"failed"` + A scroll action. - - `CustomToolCall object { call_id, input, name, 3 more }` + - `Type object { text, type }` - A call to a custom tool created by the model. + An action to type in text. - - `call_id: string` + - `Wait object { type }` - An identifier used to map this custom tool call to a tool call output. + A wait action. - - `input: string` + - `ComputerCallOutput object { id, call_id, output, 4 more }` - The input for the custom tool call generated by the model. + - `id: string` - - `name: string` + The unique ID of the computer call tool output. - The name of the custom tool being called. + - `call_id: string` - - `type: "custom_tool_call"` + The ID of the computer tool call that produced the output. - The type of the custom tool call. Always `custom_tool_call`. + - `output: ResponseComputerToolCallOutputScreenshot` - - `"custom_tool_call"` + A computer screenshot image used with the computer use tool. - - `id: optional string` + - `type: "computer_screenshot"` - The unique ID of the custom tool call in the OpenAI platform. + Specifies the event type. For a computer screenshot, this property is + always set to `computer_screenshot`. - - `namespace: optional string` + - `"computer_screenshot"` - The namespace of the custom tool being called. + - `file_id: optional string` - - `CustomToolCallOutput object { call_id, output, type, id }` + The identifier of an uploaded file that contains the screenshot. - The output of a custom tool call from your code, being sent back to the model. + - `image_url: optional string` - - `call_id: string` + The URL of the screenshot image. - The call ID, used to map this custom tool call output to a custom tool call. + - `status: "completed" or "incomplete" or "failed" or "in_progress"` - - `output: string or array of ResponseInputText or ResponseInputImage or ResponseInputFile` + The status of the message input. One of `in_progress`, `completed`, or + `incomplete`. Populated when input items are returned via API. - The output from the custom tool call generated by your code. - Can be a string or an list of output content. + - `"completed"` - - `StringOutput = string` + - `"incomplete"` - A string of the output of the custom tool call. + - `"failed"` - - `OutputContentList = array of ResponseInputText or ResponseInputImage or ResponseInputFile` + - `"in_progress"` - Text, image, or file output of the custom tool call. + - `type: "computer_call_output"` - - `ResponseInputText object { text, type }` + The type of the computer tool call output. Always `computer_call_output`. - A text input to the model. + - `"computer_call_output"` - - `ResponseInputImage object { detail, type, file_id, image_url }` + - `acknowledged_safety_checks: optional array of object { id, code, message }` - An image input to the model. Learn about [image inputs](/docs/guides/vision). + The safety checks reported by the API that have been acknowledged by the + developer. - - `ResponseInputFile object { type, detail, file_data, 3 more }` + - `id: string` - A file input to the model. + The ID of the pending safety check. - - `type: "custom_tool_call_output"` + - `code: optional string` - The type of the custom tool call output. Always `custom_tool_call_output`. + The type of the pending safety check. - - `"custom_tool_call_output"` + - `message: optional string` - - `id: optional string` + Details about the pending safety check. - The unique ID of the custom tool call output in the OpenAI platform. + - `created_by: optional string` -### Conversation Item List + The identifier of the actor that created the item. -- `ConversationItemList object { data, first_id, has_more, 2 more }` + - `ToolSearchCall object { id, arguments, call_id, 4 more }` - A list of Conversation items. + - `id: string` - - `data: array of ConversationItem` + The unique ID of the tool search call item. - A list of conversation items. + - `arguments: unknown` - - `Message object { id, content, role, 3 more }` + Arguments used for the tool search call. - A message to or from the model. + - `call_id: string` - - `id: string` + The unique ID of the tool search call generated by the model. - The unique ID of the message. + - `execution: "server" or "client"` - - `content: array of ResponseInputText or ResponseOutputText or TextContent or 6 more` + Whether tool search was executed by the server or by the client. - The content of the message + - `"server"` - - `ResponseInputText object { text, type }` + - `"client"` - A text input to the model. + - `status: "in_progress" or "completed" or "incomplete"` - - `text: string` + The status of the tool search call item that was recorded. - The text input to the model. + - `"in_progress"` - - `type: "input_text"` + - `"completed"` - The type of the input item. Always `input_text`. + - `"incomplete"` - - `"input_text"` + - `type: "tool_search_call"` - - `ResponseOutputText object { annotations, logprobs, text, type }` + The type of the item. Always `tool_search_call`. - A text output from the model. + - `"tool_search_call"` - - `annotations: array of object { file_id, filename, index, type } or object { end_index, start_index, title, 2 more } or object { container_id, end_index, file_id, 3 more } or object { file_id, index, type }` + - `created_by: optional string` - The annotations of the text output. + The identifier of the actor that created the item. - - `FileCitation object { file_id, filename, index, type }` + - `ToolSearchOutput object { id, call_id, execution, 4 more }` - A citation to a file. + - `id: string` - - `file_id: string` + The unique ID of the tool search output item. - The ID of the file. + - `call_id: string` - - `filename: string` + The unique ID of the tool search call generated by the model. - The filename of the file cited. + - `execution: "server" or "client"` - - `index: number` + Whether tool search was executed by the server or by the client. - The index of the file in the list of files. + - `"server"` - - `type: "file_citation"` + - `"client"` - The type of the file citation. Always `file_citation`. + - `status: "in_progress" or "completed" or "incomplete"` - - `"file_citation"` + The status of the tool search output item that was recorded. - - `URLCitation object { end_index, start_index, title, 2 more }` + - `"in_progress"` - A citation for a web resource used to generate a model response. + - `"completed"` - - `end_index: number` + - `"incomplete"` - The index of the last character of the URL citation in the message. + - `tools: array of object { name, parameters, strict, 3 more } or object { type, vector_store_ids, filters, 2 more } or object { type } or 12 more` - - `start_index: number` + The loaded tool definitions returned by tool search. - The index of the first character of the URL citation in the message. + - `Function object { name, parameters, strict, 3 more }` - - `title: string` + 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). - The title of the web resource. + - `name: string` - - `type: "url_citation"` + The name of the function to call. - The type of the URL citation. Always `url_citation`. + - `parameters: map[unknown]` - - `"url_citation"` + A JSON schema object describing the parameters of the function. - - `url: string` + - `strict: boolean` - The URL of the web resource. + Whether to enforce strict parameter validation. Default `true`. - - `ContainerFileCitation object { container_id, end_index, file_id, 3 more }` + - `type: "function"` - A citation for a container file used to generate a model response. + The type of the function tool. Always `function`. - - `container_id: string` + - `"function"` - The ID of the container file. + - `defer_loading: optional boolean` - - `end_index: number` + Whether this function is deferred and loaded via tool search. - The index of the last character of the container file citation in the message. + - `description: optional string` - - `file_id: string` + A description of the function. Used by the model to determine whether or not to call the function. - The ID of the file. + - `FileSearch object { type, vector_store_ids, filters, 2 more }` - - `filename: string` + A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). - The filename of the container file cited. + - `type: "file_search"` - - `start_index: number` + The type of the file search tool. Always `file_search`. - The index of the first character of the container file citation in the message. + - `"file_search"` - - `type: "container_file_citation"` + - `vector_store_ids: array of string` - The type of the container file citation. Always `container_file_citation`. + The IDs of the vector stores to search. - - `"container_file_citation"` + - `filters: optional ComparisonFilter or CompoundFilter` - - `FilePath object { file_id, index, type }` + A filter to apply. - A path to a file. + - `ComparisonFilter object { key, type, value }` - - `file_id: string` + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - The ID of the file. + - `key: string` - - `index: number` + The key to compare against the value. - The index of the file in the list of files. + - `type: "eq" or "ne" or "gt" or 5 more` - - `type: "file_path"` + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - The type of the file path. Always `file_path`. + - `eq`: equals + - `ne`: not equal + - `gt`: greater than + - `gte`: greater than or equal + - `lt`: less than + - `lte`: less than or equal + - `in`: in + - `nin`: not in - - `"file_path"` + - `"eq"` - - `logprobs: array of object { token, bytes, logprob, top_logprobs }` + - `"ne"` - - `token: string` + - `"gt"` - - `bytes: array of number` + - `"gte"` - - `logprob: number` + - `"lt"` - - `top_logprobs: array of object { token, bytes, logprob }` + - `"lte"` - - `token: string` + - `"in"` - - `bytes: array of number` + - `"nin"` - - `logprob: number` + - `value: string or number or boolean or array of string or number` - - `text: string` + The value to compare against the attribute key; supports string, number, or boolean types. - The text output from the model. + - `string` - - `type: "output_text"` + - `number` - The type of the output text. Always `output_text`. + - `boolean` - - `"output_text"` + - `array of string or number` - - `TextContent object { text, type }` + - `string` - A text content. + - `number` - - `text: string` + - `CompoundFilter object { filters, type }` - - `type: "text"` + Combine multiple filters using `and` or `or`. - - `"text"` + - `filters: array of ComparisonFilter or unknown` - - `SummaryTextContent object { text, type }` + Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. - A summary text from the model. + - `ComparisonFilter object { key, type, value }` - - `text: string` + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - A summary of the reasoning output from the model so far. + - `unknown` - - `type: "summary_text"` + - `type: "and" or "or"` - The type of the object. Always `summary_text`. + Type of operation: `and` or `or`. - - `"summary_text"` + - `"and"` - - `ReasoningText object { text, type }` + - `"or"` - Reasoning text from the model. + - `max_num_results: optional number` - - `text: string` + The maximum number of results to return. This number should be between 1 and 50 inclusive. - The reasoning text from the model. + - `ranking_options: optional object { hybrid_search, ranker, score_threshold }` - - `type: "reasoning_text"` + Ranking options for search. - The type of the reasoning text. Always `reasoning_text`. + - `hybrid_search: optional object { embedding_weight, text_weight }` - - `"reasoning_text"` + Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. - - `ResponseOutputRefusal object { refusal, type }` + - `embedding_weight: number` - A refusal from the model. + The weight of the embedding in the reciprocal ranking fusion. - - `refusal: string` + - `text_weight: number` - The refusal explanation from the model. + The weight of the text in the reciprocal ranking fusion. - - `type: "refusal"` + - `ranker: optional "auto" or "default-2024-11-15"` - The type of the refusal. Always `refusal`. + The ranker to use for the file search. - - `"refusal"` + - `"auto"` - - `ResponseInputImage object { detail, type, file_id, image_url }` + - `"default-2024-11-15"` - An image input to the model. Learn about [image inputs](/docs/guides/vision). + - `score_threshold: optional number` - - `detail: "low" or "high" or "auto" or "original"` + The score threshold for the file search, a number between 0 and 1. Numbers closer to 1 will attempt to return only the most relevant results, but may return fewer results. - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + - `Computer object { type }` - - `"low"` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `"high"` + - `type: "computer"` - - `"auto"` + The type of the computer tool. Always `computer`. - - `"original"` + - `"computer"` - - `type: "input_image"` + - `ComputerUsePreview object { display_height, display_width, environment, type }` - The type of the input item. Always `input_image`. + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `"input_image"` + - `display_height: number` - - `file_id: optional string` + The height of the computer display. - The ID of the file to be sent to the model. + - `display_width: number` - - `image_url: optional string` + The width of the computer display. - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + - `environment: "windows" or "mac" or "linux" or 2 more` - - `ComputerScreenshotContent object { detail, file_id, image_url, type }` + The type of computer environment to control. - A screenshot of a computer. + - `"windows"` - - `detail: "low" or "high" or "auto" or "original"` + - `"mac"` - The detail level of the screenshot image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + - `"linux"` - - `"low"` + - `"ubuntu"` - - `"high"` + - `"browser"` - - `"auto"` + - `type: "computer_use_preview"` - - `"original"` + The type of the computer use tool. Always `computer_use_preview`. - - `file_id: string` + - `"computer_use_preview"` - The identifier of an uploaded file that contains the screenshot. + - `WebSearch object { type, filters, search_context_size, user_location }` - - `image_url: string` + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](/docs/guides/tools-web-search). - The URL of the screenshot image. + - `type: "web_search" or "web_search_2025_08_26"` - - `type: "computer_screenshot"` + The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. - Specifies the event type. For a computer screenshot, this property is always set to `computer_screenshot`. + - `"web_search"` - - `"computer_screenshot"` + - `"web_search_2025_08_26"` - - `ResponseInputFile object { type, detail, file_data, 3 more }` + - `filters: optional object { allowed_domains }` - A file input to the model. + Filters for the search. - - `type: "input_file"` + - `allowed_domains: optional array of string` - The type of the input item. Always `input_file`. + Allowed domains for the search. If not provided, all domains are allowed. + Subdomains of the provided domains are allowed as well. - - `"input_file"` + Example: `["pubmed.ncbi.nlm.nih.gov"]` - - `detail: optional "low" or "high"` + - `search_context_size: optional "low" or "medium" 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`. + High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. - `"low"` - - `"high"` - - - `file_data: optional string` + - `"medium"` - The content of the file to be sent to the model. + - `"high"` - - `file_id: optional string` + - `user_location: optional object { city, country, region, 2 more }` - The ID of the file to be sent to the model. + The approximate location of the user. - - `file_url: optional string` + - `city: optional string` - The URL of the file to be sent to the model. + Free text input for the city of the user, e.g. `San Francisco`. - - `filename: optional string` + - `country: optional string` - The name of the file to be sent to the model. + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - - `role: "unknown" or "user" or "assistant" or 5 more` + - `region: optional string` - The role of the message. One of `unknown`, `user`, `assistant`, `system`, `critic`, `discriminator`, `developer`, or `tool`. + Free text input for the region of the user, e.g. `California`. - - `"unknown"` + - `timezone: optional string` - - `"user"` + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - - `"assistant"` + - `type: optional "approximate"` - - `"system"` + The type of location approximation. Always `approximate`. - - `"critic"` + - `"approximate"` - - `"discriminator"` + - `Mcp object { server_label, type, allowed_tools, 7 more }` - - `"developer"` + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](/docs/guides/tools-remote-mcp). - - `"tool"` + - `server_label: string` - - `status: "in_progress" or "completed" or "incomplete"` + A label for this MCP server, used to identify it in tool calls. - The status of item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. + - `type: "mcp"` - - `"in_progress"` + The type of the MCP tool. Always `mcp`. - - `"completed"` + - `"mcp"` - - `"incomplete"` + - `allowed_tools: optional array of string or object { read_only, tool_names }` - - `type: "message"` + List of allowed tool names or a filter object. - The type of the message. Always set to `message`. + - `McpAllowedTools = array of string` - - `"message"` + A string array of allowed tool names - - `phase: optional "commentary" or "final_answer"` + - `McpToolFilter object { read_only, tool_names }` - Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend phase on all assistant messages — dropping it can degrade performance. Not used for user messages. + A filter object to specify which tools are allowed. - - `"commentary"` + - `read_only: optional boolean` - - `"final_answer"` + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. - - `FunctionCall object { id, arguments, call_id, 5 more }` + - `tool_names: optional array of string` - - `id: string` + List of allowed tool names. - The unique ID of the function tool call. + - `authorization: optional string` - - `arguments: string` + An OAuth access token that can be used with a remote MCP server, either + with a custom MCP server URL or a service connector. Your application + must handle the OAuth authorization flow and provide the token here. - A JSON string of the arguments to pass to the function. + - `connector_id: optional "connector_dropbox" or "connector_gmail" or "connector_googlecalendar" or 5 more` - - `call_id: string` + Identifier for service connectors, like those available in ChatGPT. One of + `server_url` or `connector_id` must be provided. Learn more about service + connectors [here](/docs/guides/tools-remote-mcp#connectors). - The unique ID of the function tool call generated by the model. + Currently supported `connector_id` values are: - - `name: string` + - Dropbox: `connector_dropbox` + - Gmail: `connector_gmail` + - Google Calendar: `connector_googlecalendar` + - Google Drive: `connector_googledrive` + - Microsoft Teams: `connector_microsoftteams` + - Outlook Calendar: `connector_outlookcalendar` + - Outlook Email: `connector_outlookemail` + - SharePoint: `connector_sharepoint` - The name of the function to run. + - `"connector_dropbox"` - - `status: "in_progress" or "completed" or "incomplete"` + - `"connector_gmail"` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `"connector_googlecalendar"` - - `"in_progress"` + - `"connector_googledrive"` - - `"completed"` + - `"connector_microsoftteams"` - - `"incomplete"` + - `"connector_outlookcalendar"` - - `type: "function_call"` + - `"connector_outlookemail"` - The type of the function tool call. Always `function_call`. + - `"connector_sharepoint"` - - `"function_call"` + - `defer_loading: optional boolean` - - `created_by: optional string` + Whether this MCP tool is deferred and discovered via tool search. - The identifier of the actor that created the item. + - `headers: optional map[string]` - - `namespace: optional string` + Optional HTTP headers to send to the MCP server. Use for authentication + or other purposes. - The namespace of the function to run. + - `require_approval: optional object { always, never } or "always" or "never"` - - `FunctionCallOutput object { id, call_id, output, 3 more }` + Specify which of the MCP server's tools require approval. - - `id: string` + - `McpToolApprovalFilter object { always, never }` - The unique ID of the function call tool output. + Specify which of the MCP server's tools require approval. Can be + `always`, `never`, or a filter object associated with tools + that require approval. - - `call_id: string` + - `always: optional object { read_only, tool_names }` - The unique ID of the function tool call generated by the model. + A filter object to specify which tools are allowed. - - `output: string or array of ResponseInputText or ResponseInputImage or ResponseInputFile` + - `read_only: optional boolean` - The output from the function call generated by your code. - Can be a string or an list of output content. + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. - - `StringOutput = string` + - `tool_names: optional array of string` - A string of the output of the function call. + List of allowed tool names. - - `OutputContentList = array of ResponseInputText or ResponseInputImage or ResponseInputFile` + - `never: optional object { read_only, tool_names }` - Text, image, or file output of the function call. + A filter object to specify which tools are allowed. - - `ResponseInputText object { text, type }` + - `read_only: optional boolean` - A text input to the model. + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. - - `ResponseInputImage object { detail, type, file_id, image_url }` + - `tool_names: optional array of string` - An image input to the model. Learn about [image inputs](/docs/guides/vision). + List of allowed tool names. - - `ResponseInputFile object { type, detail, file_data, 3 more }` + - `McpToolApprovalSetting = "always" or "never"` - A file input to the model. + Specify a single approval policy for all tools. One of `always` or + `never`. When set to `always`, all tools will require approval. When + set to `never`, all tools will not require approval. - - `status: "in_progress" or "completed" or "incomplete"` + - `"always"` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `"never"` - - `"in_progress"` + - `server_description: optional string` - - `"completed"` + Optional description of the MCP server, used to provide more context. - - `"incomplete"` + - `server_url: optional string` - - `type: "function_call_output"` + The URL for the MCP server. One of `server_url` or `connector_id` must be + provided. - The type of the function tool call output. Always `function_call_output`. + - `CodeInterpreter object { container, type }` - - `"function_call_output"` + A tool that runs Python code to help generate a response to a prompt. - - `created_by: optional string` + - `container: string or object { type, file_ids, memory_limit, network_policy }` - The identifier of the actor that created the item. + The code interpreter container. Can be a container ID or an object that + specifies uploaded file IDs to make available to your code, along with an + optional `memory_limit` setting. - - `FileSearchCall object { id, queries, status, 2 more }` + - `string` - The results of a file search tool call. See the - [file search guide](/docs/guides/tools-file-search) for more information. + The container ID. - - `id: string` + - `CodeInterpreterToolAuto object { type, file_ids, memory_limit, network_policy }` - The unique ID of the file search tool call. + Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. - - `queries: array of string` + - `type: "auto"` - The queries used to search for files. + Always `auto`. - - `status: "in_progress" or "searching" or "completed" or 2 more` + - `"auto"` - The status of the file search tool call. One of `in_progress`, - `searching`, `incomplete` or `failed`, + - `file_ids: optional array of string` - - `"in_progress"` + An optional list of uploaded files to make available to your code. - - `"searching"` + - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` - - `"completed"` + The memory limit for the code interpreter container. - - `"incomplete"` + - `"1g"` - - `"failed"` + - `"4g"` - - `type: "file_search_call"` + - `"16g"` - The type of the file search tool call. Always `file_search_call`. + - `"64g"` - - `"file_search_call"` + - `network_policy: optional ContainerNetworkPolicyDisabled or ContainerNetworkPolicyAllowlist` - - `results: optional array of object { attributes, file_id, filename, 2 more }` + Network access policy for the container. - The results of the file search tool call. + - `ContainerNetworkPolicyDisabled object { type }` - - `attributes: optional map[string or number or boolean]` + - `type: "disabled"` - Set of 16 key-value pairs that can be attached to an object. This can be - useful for storing additional information about the object in a structured - format, and querying for objects via API or the dashboard. Keys are strings - with a maximum length of 64 characters. Values are strings with a maximum - length of 512 characters, booleans, or numbers. + Disable outbound network access. Always `disabled`. - - `string` + - `"disabled"` - - `number` + - `ContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` - - `boolean` + - `allowed_domains: array of string` - - `file_id: optional string` + A list of allowed domains when type is `allowlist`. - The unique ID of the file. + - `type: "allowlist"` - - `filename: optional string` + Allow outbound network access only to specified domains. Always `allowlist`. - The name of the file. + - `"allowlist"` - - `score: optional number` + - `domain_secrets: optional array of ContainerNetworkPolicyDomainSecret` - The relevance score of the file - a value between 0 and 1. + Optional domain-scoped secrets for allowlisted domains. - - `text: optional string` + - `domain: string` - The text that was retrieved from the file. + The domain associated with the secret. - - `WebSearchCall object { id, action, status, type }` + - `name: string` - The results of a web search tool call. See the - [web search guide](/docs/guides/tools-web-search) for more information. + The name of the secret to inject for the domain. - - `id: string` + - `value: string` - The unique ID of the web search tool call. + The secret value to inject for the domain. - - `action: object { query, type, queries, sources } or object { type, url } or object { pattern, type, url }` + - `type: "code_interpreter"` - An object describing the specific action taken in this web search call. - Includes details on how the model used the web (search, open_page, find_in_page). + The type of the code interpreter tool. Always `code_interpreter`. - - `Search object { query, type, queries, sources }` + - `"code_interpreter"` - Action type "search" - Performs a web search query. + - `ImageGeneration object { type, action, background, 9 more }` - - `query: string` + A tool that generates images using the GPT image models. - [DEPRECATED] The search query. + - `type: "image_generation"` - - `type: "search"` + The type of the image generation tool. Always `image_generation`. - The action type. + - `"image_generation"` - - `"search"` + - `action: optional "generate" or "edit" or "auto"` - - `queries: optional array of string` + Whether to generate a new image or edit an existing image. Default: `auto`. - The search queries. + - `"generate"` - - `sources: optional array of object { type, url }` + - `"edit"` - The sources used in the search. + - `"auto"` - - `type: "url"` + - `background: optional "transparent" or "opaque" or "auto"` - The type of source. Always `url`. + Background type for the generated image. One of `transparent`, + `opaque`, or `auto`. Default: `auto`. - - `"url"` + - `"transparent"` - - `url: string` + - `"opaque"` - The URL of the source. + - `"auto"` - - `OpenPage object { type, url }` + - `input_fidelity: optional "high" or "low"` - Action type "open_page" - Opens a specific URL from search results. + Control how much effort the model will exert to match the style and features, especially facial features, of input images. This parameter is only supported for `gpt-image-1` and `gpt-image-1.5` and later models, unsupported for `gpt-image-1-mini`. Supports `high` and `low`. Defaults to `low`. - - `type: "open_page"` + - `"high"` - The action type. + - `"low"` - - `"open_page"` + - `input_image_mask: optional object { file_id, image_url }` - - `url: optional string` + Optional mask for inpainting. Contains `image_url` + (string, optional) and `file_id` (string, optional). - The URL opened by the model. + - `file_id: optional string` - - `FindInPage object { pattern, type, url }` + File ID for the mask image. - Action type "find_in_page": Searches for a pattern within a loaded page. + - `image_url: optional string` - - `pattern: string` + Base64-encoded mask image. - The pattern or text to search for within the page. + - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` - - `type: "find_in_page"` + The image generation model to use. Default: `gpt-image-1`. - The action type. + - `string` - - `"find_in_page"` + - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` - - `url: string` + The image generation model to use. Default: `gpt-image-1`. - The URL of the page searched for the pattern. + - `"gpt-image-1"` - - `status: "in_progress" or "searching" or "completed" or "failed"` + - `"gpt-image-1-mini"` - The status of the web search tool call. + - `"gpt-image-1.5"` - - `"in_progress"` + - `moderation: optional "auto" or "low"` - - `"searching"` + Moderation level for the generated image. Default: `auto`. - - `"completed"` + - `"auto"` - - `"failed"` + - `"low"` - - `type: "web_search_call"` + - `output_compression: optional number` - The type of the web search tool call. Always `web_search_call`. + Compression level for the output image. Default: 100. - - `"web_search_call"` + - `output_format: optional "png" or "webp" or "jpeg"` - - `ImageGenerationCall object { id, result, status, type }` + The output format of the generated image. One of `png`, `webp`, or + `jpeg`. Default: `png`. - An image generation request made by the model. + - `"png"` - - `id: string` + - `"webp"` - The unique ID of the image generation call. + - `"jpeg"` - - `result: string` + - `partial_images: optional number` - The generated image encoded in base64. + Number of partial images to generate in streaming mode, from 0 (default value) to 3. - - `status: "in_progress" or "completed" or "generating" or "failed"` + - `quality: optional "low" or "medium" or "high" or "auto"` - The status of the image generation call. + The quality of the generated image. One of `low`, `medium`, `high`, + or `auto`. Default: `auto`. - - `"in_progress"` + - `"low"` - - `"completed"` + - `"medium"` - - `"generating"` + - `"high"` - - `"failed"` + - `"auto"` - - `type: "image_generation_call"` + - `size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or "auto"` - The type of the image generation call. Always `image_generation_call`. + The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. - - `"image_generation_call"` + - `string` - - `ComputerCall object { id, call_id, pending_safety_checks, 4 more }` + - `"1024x1024" or "1024x1536" or "1536x1024" or "auto"` - A tool call to a computer use tool. See the - [computer use guide](/docs/guides/tools-computer-use) for more information. + The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. - - `id: string` + - `"1024x1024"` - The unique ID of the computer call. + - `"1024x1536"` - - `call_id: string` + - `"1536x1024"` - An identifier used when responding to the tool call with output. + - `"auto"` - - `pending_safety_checks: array of object { id, code, message }` + - `LocalShell object { type }` - The pending safety checks for the computer call. + A tool that allows the model to execute shell commands in a local environment. - - `id: string` + - `type: "local_shell"` - The ID of the pending safety check. + The type of the local shell tool. Always `local_shell`. - - `code: optional string` + - `"local_shell"` - The type of the pending safety check. + - `Shell object { type, environment }` - - `message: optional string` + A tool that allows the model to execute shell commands. - Details about the pending safety check. + - `type: "shell"` - - `status: "in_progress" or "completed" or "incomplete"` + The type of the shell tool. Always `shell`. - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `"shell"` - - `"in_progress"` + - `environment: optional ContainerAuto or LocalEnvironment or ContainerReference` - - `"completed"` + - `ContainerAuto object { type, file_ids, memory_limit, 2 more }` - - `"incomplete"` + - `type: "container_auto"` - - `type: "computer_call"` + Automatically creates a container for this request - The type of the computer call. Always `computer_call`. + - `"container_auto"` - - `"computer_call"` + - `file_ids: optional array of string` - - `action: optional ComputerAction` + An optional list of uploaded files to make available to your code. - A click action. + - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` - - `Click object { button, type, x, 2 more }` + The memory limit for the container. - A click action. + - `"1g"` - - `button: "left" or "right" or "wheel" or 2 more` + - `"4g"` - Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. + - `"16g"` - - `"left"` + - `"64g"` - - `"right"` + - `network_policy: optional ContainerNetworkPolicyDisabled or ContainerNetworkPolicyAllowlist` - - `"wheel"` + Network access policy for the container. - - `"back"` + - `ContainerNetworkPolicyDisabled object { type }` - - `"forward"` + - `ContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` - - `type: "click"` + - `skills: optional array of SkillReference or InlineSkill` - Specifies the event type. For a click action, this property is always `click`. + An optional list of skills referenced by id or inline data. - - `"click"` + - `SkillReference object { skill_id, type, version }` - - `x: number` + - `skill_id: string` - The x-coordinate where the click occurred. + The ID of the referenced skill. - - `y: number` + - `type: "skill_reference"` - The y-coordinate where the click occurred. + References a skill created with the /v1/skills endpoint. - - `keys: optional array of string` + - `"skill_reference"` - The keys being held while clicking. + - `version: optional string` - - `DoubleClick object { keys, type, x, y }` + Optional skill version. Use a positive integer or 'latest'. Omit for default. - A double click action. + - `InlineSkill object { description, name, source, type }` - - `keys: array of string` + - `description: string` - The keys being held while double-clicking. + The description of the skill. - - `type: "double_click"` + - `name: string` - Specifies the event type. For a double click action, this property is always set to `double_click`. + The name of the skill. - - `"double_click"` + - `source: InlineSkillSource` - - `x: number` + Inline skill payload - The x-coordinate where the double click occurred. + - `data: string` - - `y: number` + Base64-encoded skill zip bundle. - The y-coordinate where the double click occurred. + - `media_type: "application/zip"` - - `Drag object { path, type, keys }` + The media type of the inline skill payload. Must be `application/zip`. - A drag action. + - `"application/zip"` - - `path: array of object { x, y }` + - `type: "base64"` - An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg + The type of the inline skill source. Must be `base64`. - ``` - [ - { x: 100, y: 200 }, - { x: 200, y: 300 } - ] - ``` + - `"base64"` - - `x: number` + - `type: "inline"` - The x-coordinate. + Defines an inline skill for this request. - - `y: number` + - `"inline"` - The y-coordinate. + - `LocalEnvironment object { type, skills }` - - `type: "drag"` + - `type: "local"` - Specifies the event type. For a drag action, this property is always set to `drag`. + Use a local computer environment. - - `"drag"` + - `"local"` - - `keys: optional array of string` + - `skills: optional array of LocalSkill` - The keys being held while dragging the mouse. + An optional list of skills. - - `Keypress object { keys, type }` + - `description: string` - A collection of keypresses the model would like to perform. + The description of the skill. - - `keys: array of string` + - `name: string` - The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. + The name of the skill. - - `type: "keypress"` + - `path: string` - Specifies the event type. For a keypress action, this property is always set to `keypress`. + The path to the directory containing the skill. - - `"keypress"` + - `ContainerReference object { container_id, type }` - - `Move object { type, x, y, keys }` + - `container_id: string` - A mouse move action. + The ID of the referenced container. - - `type: "move"` + - `type: "container_reference"` - Specifies the event type. For a move action, this property is always set to `move`. + References a container created with the /v1/containers endpoint - - `"move"` + - `"container_reference"` - - `x: number` + - `Custom object { name, type, defer_loading, 2 more }` - The x-coordinate to move to. + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) - - `y: number` + - `name: string` - The y-coordinate to move to. + The name of the custom tool, used to identify it in tool calls. - - `keys: optional array of string` + - `type: "custom"` - The keys being held while moving the mouse. + The type of the custom tool. Always `custom`. - - `Screenshot object { type }` + - `"custom"` - A screenshot action. + - `defer_loading: optional boolean` - - `type: "screenshot"` + Whether this tool should be deferred and discovered via tool search. - Specifies the event type. For a screenshot action, this property is always set to `screenshot`. + - `description: optional string` - - `"screenshot"` + Optional description of the custom tool, used to provide more context. - - `Scroll object { scroll_x, scroll_y, type, 3 more }` + - `format: optional CustomToolInputFormat` - A scroll action. + The input format for the custom tool. Default is unconstrained text. - - `scroll_x: number` + - `Text object { type }` - The horizontal scroll distance. + Unconstrained free-form text. - - `scroll_y: number` + - `type: "text"` - The vertical scroll distance. + Unconstrained text format. Always `text`. - - `type: "scroll"` + - `"text"` - Specifies the event type. For a scroll action, this property is always set to `scroll`. + - `Grammar object { definition, syntax, type }` - - `"scroll"` + A grammar defined by the user. - - `x: number` + - `definition: string` - The x-coordinate where the scroll occurred. + The grammar definition. - - `y: number` + - `syntax: "lark" or "regex"` - The y-coordinate where the scroll occurred. + The syntax of the grammar definition. One of `lark` or `regex`. - - `keys: optional array of string` + - `"lark"` - The keys being held while scrolling. + - `"regex"` - - `Type object { text, type }` + - `type: "grammar"` - An action to type in text. + Grammar format. Always `grammar`. - - `text: string` + - `"grammar"` - The text to type. + - `Namespace object { description, name, tools, type }` - - `type: "type"` + Groups function/custom tools under a shared namespace. - Specifies the event type. For a type action, this property is always set to `type`. + - `description: string` - - `"type"` + A description of the namespace shown to the model. - - `Wait object { type }` + - `name: string` - A wait action. + The namespace name used in tool calls (for example, `crm`). - - `type: "wait"` + - `tools: array of object { name, type, defer_loading, 3 more } or object { name, type, defer_loading, 2 more }` - Specifies the event type. For a wait action, this property is always set to `wait`. + The function/custom tools available inside this namespace. - - `"wait"` + - `Function object { name, type, defer_loading, 3 more }` - - `actions: optional ComputerActionList` + - `name: string` - Flattened batched actions for `computer_use`. Each action includes an - `type` discriminator and action-specific fields. + - `type: "function"` - - `Click object { button, type, x, 2 more }` + - `"function"` - A click action. + - `defer_loading: optional boolean` - - `DoubleClick object { keys, type, x, y }` + Whether this function should be deferred and discovered via tool search. - A double click action. + - `description: optional string` - - `Drag object { path, type, keys }` + - `parameters: optional unknown` - A drag action. + - `strict: optional boolean` - - `Keypress object { keys, type }` + - `Custom object { name, type, defer_loading, 2 more }` - A collection of keypresses the model would like to perform. + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) - - `Move object { type, x, y, keys }` + - `name: string` - A mouse move action. + The name of the custom tool, used to identify it in tool calls. - - `Screenshot object { type }` + - `type: "custom"` - A screenshot action. + The type of the custom tool. Always `custom`. - - `Scroll object { scroll_x, scroll_y, type, 3 more }` + - `"custom"` - A scroll action. + - `defer_loading: optional boolean` - - `Type object { text, type }` + Whether this tool should be deferred and discovered via tool search. - An action to type in text. + - `description: optional string` - - `Wait object { type }` + Optional description of the custom tool, used to provide more context. - A wait action. + - `format: optional CustomToolInputFormat` - - `ComputerCallOutput object { id, call_id, output, 4 more }` + The input format for the custom tool. Default is unconstrained text. - - `id: string` + - `type: "namespace"` - The unique ID of the computer call tool output. + The type of the tool. Always `namespace`. - - `call_id: string` + - `"namespace"` - The ID of the computer tool call that produced the output. + - `ToolSearch object { type, description, execution, parameters }` - - `output: ResponseComputerToolCallOutputScreenshot` + Hosted or BYOT tool search configuration for deferred tools. - A computer screenshot image used with the computer use tool. + - `type: "tool_search"` - - `type: "computer_screenshot"` + The type of the tool. Always `tool_search`. - Specifies the event type. For a computer screenshot, this property is - always set to `computer_screenshot`. + - `"tool_search"` - - `"computer_screenshot"` + - `description: optional string` - - `file_id: optional string` + Description shown to the model for a client-executed tool search tool. - The identifier of an uploaded file that contains the screenshot. + - `execution: optional "server" or "client"` - - `image_url: optional string` + Whether tool search is executed by the server or by the client. - The URL of the screenshot image. + - `"server"` - - `status: "completed" or "incomplete" or "failed" or "in_progress"` + - `"client"` - The status of the message input. One of `in_progress`, `completed`, or - `incomplete`. Populated when input items are returned via API. + - `parameters: optional unknown` - - `"completed"` + Parameter schema for a client-executed tool search tool. - - `"incomplete"` + - `WebSearchPreview object { type, search_content_types, search_context_size, user_location }` - - `"failed"` + This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - - `"in_progress"` + - `type: "web_search_preview" or "web_search_preview_2025_03_11"` - - `type: "computer_call_output"` + The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. - The type of the computer tool call output. Always `computer_call_output`. + - `"web_search_preview"` - - `"computer_call_output"` + - `"web_search_preview_2025_03_11"` - - `acknowledged_safety_checks: optional array of object { id, code, message }` + - `search_content_types: optional array of "text" or "image"` - The safety checks reported by the API that have been acknowledged by the - developer. + - `"text"` - - `id: string` + - `"image"` - The ID of the pending safety check. + - `search_context_size: optional "low" or "medium" or "high"` - - `code: optional string` + High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. - The type of the pending safety check. + - `"low"` - - `message: optional string` + - `"medium"` - Details about the pending safety check. + - `"high"` - - `created_by: optional string` + - `user_location: optional object { type, city, country, 2 more }` - The identifier of the actor that created the item. + The user's location. - - `ToolSearchCall object { id, arguments, call_id, 4 more }` + - `type: "approximate"` - - `id: string` + The type of location approximation. Always `approximate`. - The unique ID of the tool search call item. + - `"approximate"` - - `arguments: unknown` + - `city: optional string` - Arguments used for the tool search call. + Free text input for the city of the user, e.g. `San Francisco`. - - `call_id: string` + - `country: optional string` - The unique ID of the tool search call generated by the model. + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - - `execution: "server" or "client"` + - `region: optional string` - Whether tool search was executed by the server or by the client. + Free text input for the region of the user, e.g. `California`. - - `"server"` + - `timezone: optional string` - - `"client"` + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - - `status: "in_progress" or "completed" or "incomplete"` + - `ApplyPatch object { type }` - The status of the tool search call item that was recorded. + Allows the assistant to create, delete, or update files using unified diffs. - - `"in_progress"` + - `type: "apply_patch"` - - `"completed"` + The type of the tool. Always `apply_patch`. - - `"incomplete"` + - `"apply_patch"` - - `type: "tool_search_call"` + - `type: "tool_search_output"` - The type of the item. Always `tool_search_call`. + The type of the item. Always `tool_search_output`. - - `"tool_search_call"` + - `"tool_search_output"` - `created_by: optional string` The identifier of the actor that created the item. - - `ToolSearchOutput object { id, call_id, execution, 4 more }` + - `AdditionalTools object { id, role, tools, type }` - `id: string` - The unique ID of the tool search output item. - - - `call_id: string` + The unique ID of the additional tools item. - The unique ID of the tool search call generated by the model. + - `role: "unknown" or "user" or "assistant" or 5 more` - - `execution: "server" or "client"` + The role that provided the additional tools. - Whether tool search was executed by the server or by the client. + - `"unknown"` - - `"server"` + - `"user"` - - `"client"` + - `"assistant"` - - `status: "in_progress" or "completed" or "incomplete"` + - `"system"` - The status of the tool search output item that was recorded. + - `"critic"` - - `"in_progress"` + - `"discriminator"` - - `"completed"` + - `"developer"` - - `"incomplete"` + - `"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` - The loaded tool definitions returned by tool search. + The additional tool definitions made available at this item. - `Function object { name, parameters, strict, 3 more }` @@ -19089,77 +24620,10 @@ curl -X DELETE https://api.openai.com/v1/conversations/conv_123/items/msg_abc \ A filter used to compare a specified attribute key to a given value using a defined comparison operation. - - `key: string` - - The key to compare against the value. - - - `type: "eq" or "ne" or "gt" or 5 more` - - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - - - `eq`: equals - - `ne`: not equal - - `gt`: greater than - - `gte`: greater than or equal - - `lt`: less than - - `lte`: less than or equal - - `in`: in - - `nin`: not in - - - `"eq"` - - - `"ne"` - - - `"gt"` - - - `"gte"` - - - `"lt"` - - - `"lte"` - - - `"in"` - - - `"nin"` - - - `value: string or number or boolean or array of string or number` - - The value to compare against the attribute key; supports string, number, or boolean types. - - - `string` - - - `number` - - - `boolean` - - - `array of string or number` - - - `string` - - - `number` - - `CompoundFilter object { filters, type }` Combine multiple filters using `and` or `or`. - - `filters: array of ComparisonFilter or unknown` - - Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. - - - `ComparisonFilter object { key, type, value }` - - A filter used to compare a specified attribute key to a given value using a defined comparison operation. - - - `unknown` - - - `type: "and" or "or"` - - Type of operation: `and` or `or`. - - - `"and"` - - - `"or"` - - `max_num_results: optional number` The maximum number of results to return. This number should be between 1 and 50 inclusive. @@ -19482,40 +24946,8 @@ curl -X DELETE https://api.openai.com/v1/conversations/conv_123/items/msg_abc \ - `ContainerNetworkPolicyDisabled object { type }` - - `type: "disabled"` - - Disable outbound network access. Always `disabled`. - - - `"disabled"` - - `ContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` - - `allowed_domains: array of string` - - A list of allowed domains when type is `allowlist`. - - - `type: "allowlist"` - - Allow outbound network access only to specified domains. Always `allowlist`. - - - `"allowlist"` - - - `domain_secrets: optional array of ContainerNetworkPolicyDomainSecret` - - Optional domain-scoped secrets for allowlisted domains. - - - `domain: string` - - The domain associated with the secret. - - - `name: string` - - The name of the secret to inject for the domain. - - - `value: string` - - The secret value to inject for the domain. - - `type: "code_interpreter"` The type of the code interpreter tool. Always `code_interpreter`. @@ -19672,128 +25104,10 @@ curl -X DELETE https://api.openai.com/v1/conversations/conv_123/items/msg_abc \ - `ContainerAuto object { type, file_ids, memory_limit, 2 more }` - - `type: "container_auto"` - - Automatically creates a container for this request - - - `"container_auto"` - - - `file_ids: optional array of string` - - An optional list of uploaded files to make available to your code. - - - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` - - The memory limit for the container. - - - `"1g"` - - - `"4g"` - - - `"16g"` - - - `"64g"` - - - `network_policy: optional ContainerNetworkPolicyDisabled or ContainerNetworkPolicyAllowlist` - - Network access policy for the container. - - - `ContainerNetworkPolicyDisabled object { type }` - - - `ContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` - - - `skills: optional array of SkillReference or InlineSkill` - - An optional list of skills referenced by id or inline data. - - - `SkillReference object { skill_id, type, version }` - - - `skill_id: string` - - The ID of the referenced skill. - - - `type: "skill_reference"` - - References a skill created with the /v1/skills endpoint. - - - `"skill_reference"` - - - `version: optional string` - - Optional skill version. Use a positive integer or 'latest'. Omit for default. - - - `InlineSkill object { description, name, source, type }` - - - `description: string` - - The description of the skill. - - - `name: string` - - The name of the skill. - - - `source: InlineSkillSource` - - Inline skill payload - - - `data: string` - - Base64-encoded skill zip bundle. - - - `media_type: "application/zip"` - - The media type of the inline skill payload. Must be `application/zip`. - - - `"application/zip"` - - - `type: "base64"` - - The type of the inline skill source. Must be `base64`. - - - `"base64"` - - - `type: "inline"` - - Defines an inline skill for this request. - - - `"inline"` - - `LocalEnvironment object { type, skills }` - - `type: "local"` - - Use a local computer environment. - - - `"local"` - - - `skills: optional array of LocalSkill` - - An optional list of skills. - - - `description: string` - - The description of the skill. - - - `name: string` - - The name of the skill. - - - `path: string` - - The path to the directory containing the skill. - - `ContainerReference object { container_id, type }` - - `container_id: string` - - The ID of the referenced container. - - - `type: "container_reference"` - - References a container created with the /v1/containers endpoint - - - `"container_reference"` - - `Custom object { name, type, defer_loading, 2 more }` A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) @@ -19820,38 +25134,6 @@ curl -X DELETE https://api.openai.com/v1/conversations/conv_123/items/msg_abc \ The input format for the custom tool. Default is unconstrained text. - - `Text object { type }` - - Unconstrained free-form text. - - - `type: "text"` - - Unconstrained text format. Always `text`. - - - `"text"` - - - `Grammar object { definition, syntax, type }` - - A grammar defined by the user. - - - `definition: string` - - The grammar definition. - - - `syntax: "lark" or "regex"` - - The syntax of the grammar definition. One of `lark` or `regex`. - - - `"lark"` - - - `"regex"` - - - `type: "grammar"` - - Grammar format. Always `grammar`. - - - `"grammar"` - - `Namespace object { description, name, tools, type }` Groups function/custom tools under a shared namespace. @@ -20008,15 +25290,11 @@ curl -X DELETE https://api.openai.com/v1/conversations/conv_123/items/msg_abc \ - `"apply_patch"` - - `type: "tool_search_output"` - - The type of the item. Always `tool_search_output`. - - - `"tool_search_output"` + - `type: "additional_tools"` - - `created_by: optional string` + The type of the item. Always `additional_tools`. - The identifier of the actor that created the item. + - `"additional_tools"` - `Reasoning object { id, summary, type, 3 more }`