diff --git a/en/resources/responses/index.md b/en/resources/responses/index.md index c1037e1e..6130fc96 100644 --- a/en/resources/responses/index.md +++ b/en/resources/responses/index.md @@ -1,97 +1,105 @@ # Responses -## Create a model response +## Cancel a response -**post** `/responses` +**post** `/responses/{response_id}/cancel` -Creates a model response. Provide [text](/docs/guides/text) or -[image](/docs/guides/images) inputs to generate [text](/docs/guides/text) -or [JSON](/docs/guides/structured-outputs) outputs. Have the model call -your own [custom code](/docs/guides/function-calling) or use built-in -[tools](/docs/guides/tools) like [web search](/docs/guides/tools-web-search) -or [file search](/docs/guides/tools-file-search) to use your own data -as input for the model's response. +Cancels a model response with the given ID. Only responses created with +the `background` parameter set to `true` can be cancelled. +[Learn more](/docs/guides/background). -### Body Parameters +### Path Parameters -- `background: optional boolean` +- `response_id: string` - Whether to run the model response in the background. - [Learn more](/docs/guides/background). +### Returns -- `context_management: optional array of object { type, compact_threshold }` +- `Response object { id, created_at, error, 32 more }` - Context management configuration for this request. + - `id: string` - - `type: string` + Unique identifier for this Response. - The context management entry type. Currently only 'compaction' is supported. + - `created_at: number` - - `compact_threshold: optional number` + Unix timestamp (in seconds) of when this Response was created. - Token threshold at which compaction should be triggered for this entry. + - `error: ResponseError` -- `conversation: optional string or ResponseConversationParam` + An error object returned when the model fails to generate a Response. - The conversation that this response belongs to. Items from this conversation are prepended to `input_items` for this response request. - Input items and output items from this response are automatically added to this conversation after this response completes. + - `code: "server_error" or "rate_limit_exceeded" or "invalid_prompt" or 17 more` - - `ConversationID = string` + The error code for the response. - The unique ID of the conversation. + - `"server_error"` - - `ResponseConversationParam object { id }` + - `"rate_limit_exceeded"` - The conversation that this response belongs to. + - `"invalid_prompt"` - - `id: string` + - `"data_residency_mismatch"` - The unique ID of the conversation. + - `"bio_policy"` -- `include: optional array of ResponseIncludable` + - `"vector_store_timeout"` - Specify additional output data to include in the model response. Currently supported values are: + - `"invalid_image"` - - `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). + - `"invalid_image_format"` - - `"file_search_call.results"` + - `"invalid_base64_image"` - - `"web_search_call.results"` + - `"invalid_image_url"` - - `"web_search_call.action.sources"` + - `"image_too_large"` - - `"message.input_image.image_url"` + - `"image_too_small"` - - `"computer_call_output.output.image_url"` + - `"image_parse_error"` - - `"code_interpreter_call.outputs"` + - `"image_content_policy_violation"` - - `"reasoning.encrypted_content"` + - `"invalid_image_mode"` - - `"message.output_text.logprobs"` + - `"image_file_too_large"` -- `input: optional string or array of EasyInputMessage or object { content, role, status, type } or ResponseOutputMessage or 29 more` + - `"unsupported_image_media_type"` - Text, image, or file inputs to the model, used to generate a response. + - `"empty_image_file"` - Learn more: + - `"failed_to_download_image"` - - [Text inputs and outputs](/docs/guides/text) - - [Image inputs](/docs/guides/images) - - [File inputs](/docs/guides/pdf-files) - - [Conversation state](/docs/guides/conversation-state) - - [Function calling](/docs/guides/function-calling) + - `"image_file_not_found"` - - `TextInput = string` + - `message: string` + + A human-readable description of the error. + + - `incomplete_details: object { reason }` + + Details about why the response is incomplete. + + - `reason: optional "max_output_tokens" or "content_filter"` + + The reason why the response is incomplete. + + - `"max_output_tokens"` + + - `"content_filter"` + + - `instructions: string or array of EasyInputMessage or object { content, role, status, type } or ResponseOutputMessage or 29 more` + + A system (or developer) message inserted into the model's context. + + When using along with `previous_response_id`, the instructions from a previous + response will not be carried over to the next response. This makes it simple + to swap out system (or developer) messages in new responses. + + - `string` A text input to the model, equivalent to a text input with the - `user` role. + `developer` role. - `InputItemList = array of EasyInputMessage or object { content, role, status, type } or ResponseOutputMessage or 29 more` @@ -4131,23 +4139,7 @@ as input for the model's response. - `"program_output"` -- `instructions: optional string` - - A system (or developer) message inserted into the model's context. - - When using along with `previous_response_id`, the instructions from a previous - response will not be carried over to the next response. This makes it simple - to swap out system (or developer) messages in new responses. - -- `max_output_tokens: optional number` - - An upper bound for the number of tokens that can be generated for a response, including visible output tokens and [reasoning tokens](/docs/guides/reasoning). - -- `max_tool_calls: optional number` - - The maximum number of total calls to built-in tools that can be processed in a response. This maximum number applies across all built-in tool calls, not per individual tool. Any further attempts to call a tool by the model will be ignored. - -- `metadata: optional Metadata` + - `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 @@ -4156,7 +4148,7 @@ as input for the model's response. Keys are strings with a maximum length of 64 characters. Values are strings with a maximum length of 512 characters. -- `model: optional ResponsesModel` + - `model: ResponsesModel` Model ID used to generate the response, like `gpt-4o` or `o3`. OpenAI offers a wide range of models with different capabilities, performance @@ -4359,555 +4351,627 @@ as input for the model's response. - `"gpt-5.1-codex-max"` -- `moderation: optional object { model, policy }` + - `object: "response"` - Configuration for running moderation on the input and output of this response. + The object type of this resource - always set to `response`. - - `model: string` + - `"response"` - The moderation model to use for moderated completions, e.g. 'omni-moderation-latest'. + - `output: array of ResponseOutputItem` - - `policy: optional object { input, output }` + An array of content items generated by the model. - The policy to apply to moderated response input and output. + - The length and order of items in the `output` array is dependent + on the model's response. + - Rather than accessing the first item in the `output` array and + assuming it's an `assistant` message with the content generated by + the model, you might consider using the `output_text` property where + supported in SDKs. - - `input: optional object { mode }` + - `ResponseOutputMessage object { id, content, role, 3 more }` - The moderation policy for the response input. + An output message from the model. - - `mode: "score" or "block"` + - `FileSearchCall object { id, queries, status, 2 more }` - - `"score"` + The results of a file search tool call. See the + [file search guide](/docs/guides/tools-file-search) for more information. - - `"block"` + - `id: string` - - `output: optional object { mode }` + The unique ID of the file search tool call. - The moderation policy for the response output. + - `queries: array of string` - - `mode: "score" or "block"` + The queries used to search for files. - - `"score"` + - `status: "in_progress" or "searching" or "completed" or 2 more` - - `"block"` + The status of the file search tool call. One of `in_progress`, + `searching`, `incomplete` or `failed`, -- `parallel_tool_calls: optional boolean` + - `"in_progress"` - Whether to allow the model to run tool calls in parallel. + - `"searching"` -- `previous_response_id: optional string` + - `"completed"` - The unique ID of the previous response to the model. Use this to - create multi-turn conversations. Learn more about - [conversation state](/docs/guides/conversation-state). Cannot be used in conjunction with `conversation`. + - `"incomplete"` -- `prompt: optional ResponsePrompt` + - `"failed"` - Reference to a prompt template and its variables. - [Learn more](/docs/guides/text?api-mode=responses#reusable-prompts). + - `type: "file_search_call"` - - `id: string` + The type of the file search tool call. Always `file_search_call`. - The unique identifier of the prompt template to use. + - `"file_search_call"` - - `variables: optional map[string or ResponseInputText or ResponseInputImage or ResponseInputFile]` + - `results: optional array of object { attributes, file_id, filename, 2 more }` - Optional map of values to substitute in for variables in your - prompt. The substitution values can either be strings, or other - Response input types like images or files. + The results of the file search tool call. - - `string` + - `attributes: optional map[string or number or boolean]` - - `ResponseInputText object { text, type, prompt_cache_breakpoint }` + 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. - A text input to the model. + - `string` - - `ResponseInputImage object { detail, type, file_id, 2 more }` + - `number` - An image input to the model. Learn about [image inputs](/docs/guides/vision). + - `boolean` - - `ResponseInputFile object { type, detail, file_data, 4 more }` + - `file_id: optional string` - A file input to the model. + The unique ID of the file. - - `version: optional string` + - `filename: optional string` - Optional version of the prompt template. + The name of the file. -- `prompt_cache_key: optional string` + - `score: optional number` - Used by OpenAI to cache responses for similar requests to optimize your cache hit rates. Replaces the `user` field. [Learn more](/docs/guides/prompt-caching). + The relevance score of the file - a value between 0 and 1. -- `prompt_cache_options: optional object { mode, ttl }` + - `text: optional string` - Options for prompt caching. Supported for `gpt-5.6` and later models. By default, OpenAI automatically chooses one implicit cache breakpoint. You can add explicit breakpoints to content blocks with `prompt_cache_breakpoint`. Each request can write up to four breakpoints. For cache matching, OpenAI considers up to the latest 80 breakpoints in the conversation, without a content-block lookback limit. Set `mode` to `explicit` to disable the implicit breakpoint. The `ttl` defaults to `30m`, which is currently the only supported value. See the [prompt caching guide](/docs/guides/prompt-caching) for current details. + The text that was retrieved from the file. - - `mode: optional "implicit" or "explicit"` + - `FunctionCall object { arguments, call_id, name, 5 more }` - Controls whether OpenAI automatically creates an implicit cache breakpoint. Defaults to `implicit`. With `implicit`, OpenAI creates one implicit breakpoint and writes up to the latest three explicit breakpoints in the request. With `explicit`, OpenAI does not create an implicit breakpoint and writes up to the latest four explicit breakpoints. If there are no explicit breakpoints, the request does not use prompt caching. + A tool call to run a function. See the + [function calling guide](/docs/guides/function-calling) for more information. - - `"implicit"` + - `arguments: string` - - `"explicit"` + A JSON string of the arguments to pass to the function. - - `ttl: optional "30m"` + - `call_id: string` - The minimum lifetime applied to every implicit and explicit cache breakpoint written by the request. Defaults to `30m`, which is currently the only supported value. The backend may retain cache entries for longer. + The unique ID of the function tool call generated by the model. - - `"30m"` + - `name: string` -- `prompt_cache_retention: optional "in_memory" or "24h"` + The name of the function to run. - Deprecated. Use `prompt_cache_options.ttl` instead. + - `type: "function_call"` - The retention policy for the prompt cache. Set to `24h` to enable extended prompt caching, which keeps cached prefixes active for longer, up to a maximum of 24 hours. [Learn more](/docs/guides/prompt-caching#prompt-cache-retention). - This field expresses a maximum retention policy, while - `prompt_cache_options.ttl` expresses a minimum cache lifetime. The two - fields are independent and do not interact. - For `gpt-5.5`, `gpt-5.5-pro`, and future models, only `24h` is supported. + The type of the function tool call. Always `function_call`. - For older models that support both `in_memory` and `24h`, the default depends on your organization's data retention policy: + - `"function_call"` - - Organizations without ZDR enabled default to `24h`. - - Organizations with ZDR enabled default to `in_memory` when `prompt_cache_retention` is not specified. + - `id: optional string` - - `"in_memory"` + The unique ID of the function tool call. - - `"24h"` + - `caller: optional object { type } or object { caller_id, type }` -- `reasoning: optional Reasoning` + The execution context that produced this tool call. - **gpt-5 and o-series models only** + - `Direct object { type }` - Configuration options for - [reasoning models](https://platform.openai.com/docs/guides/reasoning). + - `type: "direct"` - - `context: optional "auto" or "current_turn" or "all_turns"` + - `"direct"` - Controls which reasoning items are rendered back to the model on later turns. - If omitted or set to `auto`, the model determines the context mode. The - `gpt-5.6` model family defaults to `all_turns`; earlier models default to - `current_turn`. + - `Program object { caller_id, type }` - When returned on a response, this is the effective reasoning context mode - used for the response. + - `caller_id: string` - - `"auto"` + The call ID of the program item that produced this tool call. - - `"current_turn"` + - `type: "program"` - - `"all_turns"` + - `"program"` - - `effort: optional ReasoningEffort` + - `namespace: optional string` - Constrains effort on reasoning for reasoning models. Currently supported - values are `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max`. - Reducing reasoning effort can result in faster responses and fewer tokens - used on reasoning in a response. Not all reasoning models support every - value. See the - [reasoning guide](https://platform.openai.com/docs/guides/reasoning) - for model-specific support. + The namespace of the function to run. - - `"none"` + - `status: optional "in_progress" or "completed" or "incomplete"` - - `"minimal"` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `"low"` + - `"in_progress"` - - `"medium"` + - `"completed"` - - `"high"` + - `"incomplete"` - - `"xhigh"` + - `FunctionCallOutput object { id, call_id, output, 4 more }` - - `"max"` + - `id: string` - - `generate_summary: optional "auto" or "concise" or "detailed"` + The unique ID of the function call tool output. - **Deprecated:** use `summary` instead. + - `call_id: string` - A summary of the reasoning performed by the model. This can be - useful for debugging and understanding the model's reasoning process. - One of `auto`, `concise`, or `detailed`. + The unique ID of the function tool call generated by the model. - - `"auto"` + - `output: string or array of ResponseInputText or ResponseInputImage or ResponseInputFile` - - `"concise"` + The output from the function call generated by your code. + Can be a string or an list of output content. - - `"detailed"` + - `StringOutput = string` - - `mode: optional string or "standard" or "pro"` + A string of the output of the function call. - Controls the reasoning execution mode for the request. + - `OutputContentList = array of ResponseInputText or ResponseInputImage or ResponseInputFile` - When returned on a response, this is the effective execution mode. + Text, image, or file output of the function call. - - `string` + - `ResponseInputText object { text, type, prompt_cache_breakpoint }` - - `"standard" or "pro"` + A text input to the model. - Controls the reasoning execution mode for the request. + - `ResponseInputImage object { detail, type, file_id, 2 more }` - When returned on a response, this is the effective execution mode. + An image input to the model. Learn about [image inputs](/docs/guides/vision). - - `"standard"` + - `ResponseInputFile object { type, detail, file_data, 4 more }` - - `"pro"` + A file input to the model. - - `summary: optional "auto" or "concise" or "detailed"` + - `status: "in_progress" or "completed" or "incomplete"` - A summary of the reasoning performed by the model. This can be - useful for debugging and understanding the model's reasoning process. - One of `auto`, `concise`, or `detailed`. + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - `concise` is supported for `computer-use-preview` models and all reasoning models after `gpt-5`. + - `"in_progress"` - - `"auto"` + - `"completed"` - - `"concise"` + - `"incomplete"` - - `"detailed"` + - `type: "function_call_output"` -- `safety_identifier: optional string` + The type of the function tool call output. Always `function_call_output`. - A stable identifier used to help detect users of your application that may be violating OpenAI's usage policies. - The IDs should be a string that uniquely identifies each user, with a maximum length of 64 characters. We recommend hashing their username or email address, in order to avoid sending us any identifying information. [Learn more](/docs/guides/safety-best-practices#safety-identifiers). + - `"function_call_output"` -- `service_tier: optional "auto" or "default" or "flex" or 2 more` + - `caller: optional object { type } or object { caller_id, type }` - Specifies the processing type used for serving the request. + The execution context that produced this tool call. - - If set to 'auto', then the request will be processed with the service tier configured in the Project settings. Unless otherwise configured, the Project will use 'default'. - - If set to 'default', then the request will be processed with the standard pricing and performance for the selected model. - - If set to '[flex](/docs/guides/flex-processing)' or '[priority](https://openai.com/api-priority-processing/)', then the request will be processed with the corresponding service tier. - - When not set, the default behavior is 'auto'. + - `Direct object { type }` - When the `service_tier` parameter is set, the response body will include the `service_tier` value based on the processing mode actually used to serve the request. This response value may be different from the value set in the parameter. + - `type: "direct"` - - `"auto"` + The caller type. Always `direct`. - - `"default"` + - `"direct"` - - `"flex"` + - `Program object { caller_id, type }` - - `"scale"` + - `caller_id: string` - - `"priority"` + The call ID of the program item that produced this tool call. -- `store: optional boolean` + - `type: "program"` - Whether to store the generated model response for later retrieval via - API. + The caller type. Always `program`. -- `stream: optional boolean` + - `"program"` - If set to true, the model response data will be streamed to the client - as it is generated using [server-sent events](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events/Using_server-sent_events#Event_stream_format). - See the [Streaming section below](/docs/api-reference/responses-streaming) - for more information. + - `created_by: optional string` -- `stream_options: optional object { include_obfuscation }` + The identifier of the actor that created the item. - Options for streaming responses. Only set this when you set `stream: true`. + - `WebSearchCall object { id, action, status, type }` - - `include_obfuscation: optional boolean` + The results of a web search tool call. See the + [web search guide](/docs/guides/tools-web-search) for more information. - When true, stream obfuscation will be enabled. Stream obfuscation adds - random characters to an `obfuscation` field on streaming delta events to - normalize payload sizes as a mitigation to certain side-channel attacks. - These obfuscation fields are included by default, but add a small amount - of overhead to the data stream. You can set `include_obfuscation` to - false to optimize for bandwidth if you trust the network links between - your application and the OpenAI API. + - `id: string` -- `temperature: optional number` + The unique ID of the web search tool call. - What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. - We generally recommend altering this or `top_p` but not both. + - `action: object { type, queries, query, sources } or object { type, url } or object { pattern, type, url }` -- `text: optional ResponseTextConfig` + 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). - Configuration options for a text response from the model. Can be plain - text or structured JSON data. Learn more: + - `Search object { type, queries, query, sources }` - - [Text inputs and outputs](/docs/guides/text) - - [Structured Outputs](/docs/guides/structured-outputs) + Action type "search" - Performs a web search query. - - `format: optional ResponseFormatTextConfig` + - `type: "search"` - An object specifying the format that the model must output. + The action type. - Configuring `{ "type": "json_schema" }` enables Structured Outputs, - which ensures the model will match your supplied JSON schema. Learn more in the - [Structured Outputs guide](/docs/guides/structured-outputs). + - `"search"` - The default format is `{ "type": "text" }` with no additional options. + - `queries: optional array of string` - **Not recommended for gpt-4o and newer models:** + The search queries. - Setting to `{ "type": "json_object" }` enables the older JSON mode, which - ensures the message the model generates is valid JSON. Using `json_schema` - is preferred for models that support it. + - `query: optional string` - - `ResponseFormatText object { type }` + The search query. - Default response format. Used to generate text responses. + - `sources: optional array of object { type, url }` - - `type: "text"` + The sources used in the search. - The type of response format being defined. Always `text`. + - `type: "url"` - - `"text"` + The type of source. Always `url`. - - `ResponseFormatTextJSONSchemaConfig object { name, schema, type, 2 more }` + - `"url"` - JSON Schema response format. Used to generate structured JSON responses. - Learn more about [Structured Outputs](/docs/guides/structured-outputs). + - `url: string` - - `name: string` + The URL of the source. - The name of the response format. Must be a-z, A-Z, 0-9, or contain - underscores and dashes, with a maximum length of 64. + - `OpenPage object { type, url }` - - `schema: map[unknown]` + Action type "open_page" - Opens a specific URL from search results. - The schema for the response format, described as a JSON Schema object. - Learn how to build JSON schemas [here](https://json-schema.org/). + - `type: "open_page"` - - `type: "json_schema"` + The action type. - The type of response format being defined. Always `json_schema`. + - `"open_page"` - - `"json_schema"` + - `url: optional string` - - `description: optional string` + The URL opened by the model. - A description of what the response format is for, used by the model to - determine how to respond in the format. + - `FindInPage object { pattern, type, url }` - - `strict: optional boolean` + Action type "find_in_page": Searches for a pattern within a loaded page. - Whether to enable strict schema adherence when generating the output. - If set to true, the model will always follow the exact schema defined - in the `schema` field. Only a subset of JSON Schema is supported when - `strict` is `true`. To learn more, read the [Structured Outputs - guide](/docs/guides/structured-outputs). + - `pattern: string` - - `ResponseFormatJSONObject object { type }` + The pattern or text to search for within the page. - JSON object response format. An older method of generating JSON responses. - Using `json_schema` is recommended for models that support it. Note that the - model will not generate JSON without a system or user message instructing it - to do so. + - `type: "find_in_page"` - - `type: "json_object"` + The action type. - The type of response format being defined. Always `json_object`. + - `"find_in_page"` - - `"json_object"` + - `url: string` - - `verbosity: optional "low" or "medium" or "high"` + The URL of the page searched for the pattern. - Constrains the verbosity of the model's response. Lower values will result in - more concise responses, while higher values will result in more verbose responses. - Currently supported values are `low`, `medium`, and `high`. The default is - `medium`. + - `status: "in_progress" or "searching" or "completed" or "failed"` - - `"low"` + The status of the web search tool call. - - `"medium"` + - `"in_progress"` - - `"high"` + - `"searching"` -- `tool_choice: optional ToolChoiceOptions or ToolChoiceAllowed or ToolChoiceTypes or 6 more` + - `"completed"` - How the model should select which tool (or tools) to use when generating - a response. See the `tools` parameter to see how to specify which tools - the model can call. + - `"failed"` - - `ToolChoiceOptions = "none" or "auto" or "required"` + - `type: "web_search_call"` - Controls which (if any) tool is called by the model. + The type of the web search tool call. Always `web_search_call`. - `none` means the model will not call any tool and instead generates a message. + - `"web_search_call"` - `auto` means the model can pick between generating a message or calling one or - more tools. + - `ComputerCall object { id, call_id, pending_safety_checks, 4 more }` - `required` means the model must call one or more tools. + A tool call to a computer use tool. See the + [computer use guide](/docs/guides/tools-computer-use) for more information. - - `"none"` + - `id: string` - - `"auto"` + The unique ID of the computer call. - - `"required"` + - `call_id: string` - - `ToolChoiceAllowed object { mode, tools, type }` + An identifier used when responding to the tool call with output. - Constrains the tools available to the model to a pre-defined set. + - `pending_safety_checks: array of object { id, code, message }` - - `mode: "auto" or "required"` + The pending safety checks for the computer call. - Constrains the tools available to the model to a pre-defined set. + - `id: string` - `auto` allows the model to pick from among the allowed tools and generate a - message. + The ID of the pending safety check. - `required` requires the model to call one or more of the allowed tools. + - `code: optional string` - - `"auto"` + The type of the pending safety check. - - `"required"` + - `message: optional string` - - `tools: array of map[unknown]` + Details about the pending safety check. - A list of tool definitions that the model should be allowed to call. + - `status: "in_progress" or "completed" or "incomplete"` - For the Responses API, the list of tool definitions might look like: + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - ```json - [ - { "type": "function", "name": "get_weather" }, - { "type": "mcp", "server_label": "deepwiki" }, - { "type": "image_generation" } - ] - ``` + - `"in_progress"` - - `type: "allowed_tools"` + - `"completed"` - Allowed tool configuration type. Always `allowed_tools`. + - `"incomplete"` - - `"allowed_tools"` + - `type: "computer_call"` - - `ToolChoiceTypes object { type }` + The type of the computer call. Always `computer_call`. - Indicates that the model should use a built-in tool to generate a response. - [Learn more about built-in tools](/docs/guides/tools). + - `"computer_call"` - - `type: "file_search" or "web_search_preview" or "computer" or 5 more` + - `action: optional ComputerAction` - The type of hosted tool the model should to use. Learn more about - [built-in tools](/docs/guides/tools). + A click action. - Allowed values are: + - `actions: optional ComputerActionList` - - `file_search` - - `web_search_preview` - - `computer` - - `computer_use_preview` - - `computer_use` - - `code_interpreter` - - `image_generation` + Flattened batched actions for `computer_use`. Each action includes an + `type` discriminator and action-specific fields. - - `"file_search"` + - `ComputerCallOutput object { id, call_id, output, 4 more }` - - `"web_search_preview"` + - `id: string` - - `"computer"` + The unique ID of the computer call tool output. - - `"computer_use_preview"` + - `call_id: string` - - `"computer_use"` + The ID of the computer tool call that produced the output. - - `"web_search_preview_2025_03_11"` + - `output: ResponseComputerToolCallOutputScreenshot` - - `"image_generation"` + A computer screenshot image used with the computer use tool. - - `"code_interpreter"` + - `status: "completed" or "incomplete" or "failed" or "in_progress"` - - `ToolChoiceFunction object { name, type }` + The status of the message input. One of `in_progress`, `completed`, or + `incomplete`. Populated when input items are returned via API. - Use this option to force the model to call a specific function. + - `"completed"` - - `name: string` + - `"incomplete"` - The name of the function to call. + - `"failed"` - - `type: "function"` + - `"in_progress"` - For function calling, the type is always `function`. + - `type: "computer_call_output"` - - `"function"` + The type of the computer tool call output. Always `computer_call_output`. - - `ToolChoiceMcp object { server_label, type, name }` + - `"computer_call_output"` - Use this option to force the model to call a specific tool on a remote MCP server. + - `acknowledged_safety_checks: optional array of object { id, code, message }` - - `server_label: string` + The safety checks reported by the API that have been acknowledged by the + developer. - The label of the MCP server to use. + - `id: string` - - `type: "mcp"` + The ID of the pending safety check. - For MCP tools, the type is always `mcp`. + - `code: optional string` - - `"mcp"` + The type of the pending safety check. - - `name: optional string` + - `message: optional string` - The name of the tool to call on the server. + Details about the pending safety check. - - `ToolChoiceCustom object { name, type }` + - `created_by: optional string` - Use this option to force the model to call a specific custom tool. + The identifier of the actor that created the item. - - `name: string` + - `Reasoning object { id, summary, type, 3 more }` - The name of the custom tool to call. + 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: "custom"` + - `id: string` - For custom tool calling, the type is always `custom`. + The unique identifier of the reasoning content. - - `"custom"` + - `summary: array of SummaryTextContent` - - `SpecificProgrammaticToolCallingParam object { type }` + Reasoning summary content. - - `type: "programmatic_tool_calling"` + - `text: string` - The tool to call. Always `programmatic_tool_calling`. + A summary of the reasoning output from the model so far. - - `"programmatic_tool_calling"` + - `type: "summary_text"` - - `ToolChoiceApplyPatch object { type }` + The type of the object. Always `summary_text`. - Forces the model to call the apply_patch tool when executing a tool call. + - `type: "reasoning"` - - `type: "apply_patch"` + The type of the object. Always `reasoning`. - The tool to call. Always `apply_patch`. + - `"reasoning"` - - `"apply_patch"` + - `content: optional array of object { text, type }` - - `ToolChoiceShell object { type }` + Reasoning text content. - Forces the model to call the shell tool when a tool call is required. + - `text: string` - - `type: "shell"` + The reasoning text from the model. - The tool to call. Always `shell`. + - `type: "reasoning_text"` - - `"shell"` + The type of the reasoning text. Always `reasoning_text`. -- `tools: optional array of object { name, parameters, strict, 5 more } or object { type, vector_store_ids, filters, 2 more } or object { type } or 13 more` + - `"reasoning_text"` - An array of tools the model may call while generating a response. You - can specify which tool to use by setting the `tool_choice` parameter. + - `encrypted_content: optional string` - We support the following categories of tools: + The encrypted content of the reasoning item. This is populated by default + for reasoning items returned by `POST /v1/responses` and WebSocket + `response.create` requests. - - **Built-in tools**: Tools that are provided by OpenAI that extend the - model's capabilities, like [web search](/docs/guides/tools-web-search) - or [file search](/docs/guides/tools-file-search). Learn more about - [built-in tools](/docs/guides/tools). - - **MCP Tools**: Integrations with third-party systems via custom MCP servers - or predefined connectors such as Google Drive and SharePoint. Learn more about - [MCP Tools](/docs/guides/tools-connectors-mcp). - - **Function calls (custom tools)**: Functions that are defined by you, - enabling the model to call your own code with strongly typed arguments - and outputs. Learn more about - [function calling](/docs/guides/function-calling). You can also use - custom tools to call your own code. + - `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"` + + - `Program object { id, call_id, code, 2 more }` + + - `id: string` + + The unique ID of the program item. + + - `call_id: string` + + The stable call ID of the program item. + + - `code: string` + + The JavaScript source executed by programmatic tool calling. + + - `fingerprint: string` + + Opaque program replay fingerprint that must be round-tripped. + + - `type: "program"` + + The type of the item. Always `program`. + + - `"program"` + + - `ProgramOutput object { id, call_id, result, 2 more }` + + - `id: string` + + The unique ID of the program output item. + + - `call_id: string` + + The call ID of the program item. + + - `result: string` + + The result produced by the program item. + + - `status: "completed" or "incomplete"` + + The terminal status of the program output item. + + - `"completed"` + + - `"incomplete"` + + - `type: "program_output"` + + The type of the item. Always `program_output`. + + - `"program_output"` + + - `ToolSearchCall object { id, arguments, call_id, 4 more }` + + - `id: string` + + The unique ID of the tool search call item. + + - `arguments: unknown` + + Arguments used for the tool search call. + + - `call_id: string` + + 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 tool search call item that was recorded. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `type: "tool_search_call"` + + The type of the item. Always `tool_search_call`. + + - `"tool_search_call"` + + - `created_by: optional string` + + The identifier of the actor that created the item. + + - `ToolSearchOutput object { id, call_id, execution, 4 more }` + + - `id: string` + + The unique ID of the tool search output item. + + - `call_id: string` + + 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 tool search output item that was recorded. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `tools: array of object { name, parameters, strict, 5 more } or object { type, vector_store_ids, filters, 2 more } or object { type } or 13 more` + + The loaded tool definitions returned by tool search. - `Function object { name, parameters, strict, 5 more }` @@ -5718,1088 +5782,1061 @@ as input for the model's response. - `"programmatic"` -- `top_logprobs: optional number` - - An integer between 0 and 20 specifying the maximum number of most likely - tokens to return at each token position, each with an associated log - probability. In some cases, the number of returned tokens may be fewer than - requested. + - `type: "tool_search_output"` -- `top_p: optional number` + The type of the item. Always `tool_search_output`. - An alternative to sampling with temperature, called nucleus sampling, - where the model considers the results of the tokens with top_p probability - mass. So 0.1 means only the tokens comprising the top 10% probability mass - are considered. + - `"tool_search_output"` - We generally recommend altering this or `temperature` but not both. + - `created_by: optional string` -- `truncation: optional "auto" or "disabled"` + The identifier of the actor that created the item. - The truncation strategy to use for the model response. + - `AdditionalTools object { id, role, tools, type }` - - `auto`: If the input to this Response exceeds - the model's context window size, the model will truncate the - response to fit the context window by dropping items from the beginning of the conversation. - - `disabled` (default): If the input size will exceed the context window - size for a model, the request will fail with a 400 error. + - `id: string` - - `"auto"` + The unique ID of the additional tools item. - - `"disabled"` + - `role: "unknown" or "user" or "assistant" or 5 more` -- `user: optional string` + The role that provided the additional tools. - This field is being replaced by `safety_identifier` and `prompt_cache_key`. Use `prompt_cache_key` instead to maintain caching optimizations. - A stable identifier for your end-users. - Used to boost cache hit rates by better bucketing similar requests and to help OpenAI detect and prevent abuse. [Learn more](/docs/guides/safety-best-practices#safety-identifiers). + - `"unknown"` -### Returns + - `"user"` -- `Response object { id, created_at, error, 32 more }` + - `"assistant"` - - `id: string` + - `"system"` - Unique identifier for this Response. + - `"critic"` - - `created_at: number` + - `"discriminator"` - Unix timestamp (in seconds) of when this Response was created. + - `"developer"` - - `error: ResponseError` + - `"tool"` - An error object returned when the model fails to generate a Response. + - `tools: array of object { name, parameters, strict, 5 more } or object { type, vector_store_ids, filters, 2 more } or object { type } or 13 more` - - `code: "server_error" or "rate_limit_exceeded" or "invalid_prompt" or 17 more` + The additional tool definitions made available at this item. - The error code for the response. + - `Function object { name, parameters, strict, 5 more }` - - `"server_error"` + 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). - - `"rate_limit_exceeded"` + - `name: string` - - `"invalid_prompt"` + The name of the function to call. - - `"data_residency_mismatch"` + - `parameters: map[unknown]` - - `"bio_policy"` + A JSON schema object describing the parameters of the function. - - `"vector_store_timeout"` + - `strict: boolean` - - `"invalid_image"` + Whether strict parameter validation is enforced for this function tool. - - `"invalid_image_format"` + - `type: "function"` - - `"invalid_base64_image"` + The type of the function tool. Always `function`. - - `"invalid_image_url"` + - `"function"` - - `"image_too_large"` + - `allowed_callers: optional array of "direct" or "programmatic"` - - `"image_too_small"` + The tool invocation context(s). - - `"image_parse_error"` + - `"direct"` - - `"image_content_policy_violation"` + - `"programmatic"` - - `"invalid_image_mode"` + - `defer_loading: optional boolean` - - `"image_file_too_large"` + Whether this function is deferred and loaded via tool search. - - `"unsupported_image_media_type"` + - `description: optional string` - - `"empty_image_file"` + A description of the function. Used by the model to determine whether or not to call the function. - - `"failed_to_download_image"` + - `output_schema: optional map[unknown]` - - `"image_file_not_found"` + A JSON schema object describing the JSON value encoded in string outputs for this function. - - `message: string` + - `FileSearch object { type, vector_store_ids, filters, 2 more }` - A human-readable description of the error. + 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). - - `incomplete_details: object { reason }` + - `type: "file_search"` - Details about why the response is incomplete. + The type of the file search tool. Always `file_search`. - - `reason: optional "max_output_tokens" or "content_filter"` + - `"file_search"` - The reason why the response is incomplete. + - `vector_store_ids: array of string` - - `"max_output_tokens"` + The IDs of the vector stores to search. - - `"content_filter"` + - `filters: optional ComparisonFilter or CompoundFilter` - - `instructions: string or array of EasyInputMessage or object { content, role, status, type } or ResponseOutputMessage or 29 more` + A filter to apply. - A system (or developer) message inserted into the model's context. + - `ComparisonFilter object { key, type, value }` - When using along with `previous_response_id`, the instructions from a previous - response will not be carried over to the next response. This makes it simple - to swap out system (or developer) messages in new responses. + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - - `string` + - `CompoundFilter object { filters, type }` - A text input to the model, equivalent to a text input with the - `developer` role. + Combine multiple filters using `and` or `or`. - - `InputItemList = array of EasyInputMessage or object { content, role, status, type } or ResponseOutputMessage or 29 more` + - `max_num_results: optional number` - A list of one or many input items to the model, containing - different content types. + The maximum number of results to return. This number should be between 1 and 50 inclusive. - - `EasyInputMessage object { content, role, phase, type }` + - `ranking_options: optional object { hybrid_search, ranker, score_threshold }` - 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. + Ranking options for search. - - `content: string or ResponseInputMessageContentList` + - `hybrid_search: optional object { embedding_weight, text_weight }` - Text, image, or audio input to the model, used to generate a response. - Can also contain previous assistant responses. + Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. - - `TextInput = string` + - `embedding_weight: number` - A text input to the model. + The weight of the embedding in the reciprocal ranking fusion. - - `ResponseInputMessageContentList = array of ResponseInputContent` + - `text_weight: number` - A list of one or many input items to the model, containing different content - types. + The weight of the text in the reciprocal ranking fusion. - - `ResponseInputText object { text, type, prompt_cache_breakpoint }` + - `ranker: optional "auto" or "default-2024-11-15"` - A text input to the model. + The ranker to use for the file search. - - `text: string` + - `"auto"` - The text input to the model. + - `"default-2024-11-15"` - - `type: "input_text"` + - `score_threshold: optional number` - The type of the input item. Always `input_text`. + 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. - - `"input_text"` + - `Computer object { type }` - - `prompt_cache_breakpoint: optional object { mode }` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + - `type: "computer"` - - `mode: "explicit"` + The type of the computer tool. Always `computer`. - The breakpoint mode. Always `explicit`. + - `"computer"` - - `"explicit"` + - `ComputerUsePreview object { display_height, display_width, environment, type }` - - `ResponseInputImage object { detail, type, file_id, 2 more }` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - An image input to the model. Learn about [image inputs](/docs/guides/vision). + - `display_height: number` - - `detail: "low" or "high" or "auto" or "original"` + The height of the computer display. - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + - `display_width: number` - - `"low"` + The width of the computer display. - - `"high"` + - `environment: "windows" or "mac" or "linux" or 2 more` - - `"auto"` + The type of computer environment to control. - - `"original"` + - `"windows"` - - `type: "input_image"` + - `"mac"` - The type of the input item. Always `input_image`. + - `"linux"` - - `"input_image"` + - `"ubuntu"` - - `file_id: optional string` + - `"browser"` - The ID of the file to be sent to the model. + - `type: "computer_use_preview"` - - `image_url: optional string` + The type of the computer use tool. Always `computer_use_preview`. - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + - `"computer_use_preview"` - - `prompt_cache_breakpoint: optional object { mode }` + - `WebSearch object { type, filters, search_context_size, user_location }` - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](/docs/guides/tools-web-search). - - `mode: "explicit"` + - `type: "web_search" or "web_search_2025_08_26"` - The breakpoint mode. Always `explicit`. + The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. - - `"explicit"` + - `"web_search"` - - `ResponseInputFile object { type, detail, file_data, 4 more }` + - `"web_search_2025_08_26"` - A file input to the model. + - `filters: optional object { allowed_domains }` - - `type: "input_file"` + Filters for the search. - The type of the input item. Always `input_file`. + - `allowed_domains: optional array of string` - - `"input_file"` + Allowed domains for the search. If not provided, all domains are allowed. + Subdomains of the provided domains are allowed as well. - - `detail: optional "auto" or "low" or "high"` + Example: `["pubmed.ncbi.nlm.nih.gov"]` - The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. + - `search_context_size: optional "low" or "medium" or "high"` - - `"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"` - - `file_data: optional string` + - `user_location: optional object { city, country, region, 2 more }` - The content of the file to be sent to the model. + The approximate location of the user. - - `file_id: optional string` + - `city: optional string` - The ID of the file to be sent to the model. + Free text input for the city of the user, e.g. `San Francisco`. - - `file_url: optional string` + - `country: optional string` - The URL 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`. - - `filename: optional string` + - `region: optional string` - The name of the file to be sent to the model. + Free text input for the region of the user, e.g. `California`. - - `prompt_cache_breakpoint: optional object { mode }` + - `timezone: optional string` - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - - `mode: "explicit"` + - `type: optional "approximate"` - The breakpoint mode. Always `explicit`. + The type of location approximation. Always `approximate`. - - `"explicit"` + - `"approximate"` - - `role: "user" or "assistant" or "system" or "developer"` + - `Mcp object { server_label, type, allowed_callers, 9 more }` - The role of the message input. One of `user`, `assistant`, `system`, or - `developer`. + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](/docs/guides/tools-remote-mcp). - - `"user"` + - `server_label: string` - - `"assistant"` + A label for this MCP server, used to identify it in tool calls. - - `"system"` + - `type: "mcp"` - - `"developer"` + The type of the MCP tool. Always `mcp`. - - `phase: optional "commentary" or "final_answer"` + - `"mcp"` - 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. + - `allowed_callers: optional array of "direct" or "programmatic"` - - `"commentary"` + The tool invocation context(s). - - `"final_answer"` + - `"direct"` - - `type: optional "message"` + - `"programmatic"` - The type of the message input. Always `message`. + - `allowed_tools: optional array of string or object { read_only, tool_names }` - - `"message"` + List of allowed tool names or a filter object. - - `Message object { content, role, status, type }` + - `McpAllowedTools = array of string` - 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. + A string array of allowed tool names - - `content: ResponseInputMessageContentList` + - `McpToolFilter object { read_only, tool_names }` - A list of one or many input items to the model, containing different content - types. + A filter object to specify which tools are allowed. - - `role: "user" or "system" or "developer"` + - `read_only: optional boolean` - The role of the message input. One of `user`, `system`, or `developer`. + 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. - - `"user"` + - `tool_names: optional array of string` - - `"system"` + List of allowed tool names. - - `"developer"` + - `authorization: optional string` - - `status: optional "in_progress" or "completed" or "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. - The status of item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `connector_id: optional "connector_dropbox" or "connector_gmail" or "connector_googlecalendar" or 5 more` - - `"in_progress"` + Identifier for service connectors, like those available in ChatGPT. One of + `server_url`, `connector_id`, or `tunnel_id` must be provided. Learn more + about service connectors [here](/docs/guides/tools-remote-mcp#connectors). - - `"completed"` + Currently supported `connector_id` values are: - - `"incomplete"` + - 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: optional "message"` + - `"connector_dropbox"` - The type of the message input. Always set to `message`. + - `"connector_gmail"` - - `"message"` + - `"connector_googlecalendar"` - - `ResponseOutputMessage object { id, content, role, 3 more }` + - `"connector_googledrive"` - An output message from the model. + - `"connector_microsoftteams"` - - `id: string` + - `"connector_outlookcalendar"` - The unique ID of the output message. + - `"connector_outlookemail"` - - `content: array of ResponseOutputText or ResponseOutputRefusal` + - `"connector_sharepoint"` - The content of the output message. + - `defer_loading: optional boolean` - - `ResponseOutputText object { annotations, logprobs, text, type }` + Whether this MCP tool is deferred and discovered via tool search. - A text output from the model. + - `headers: optional map[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 }` + Optional HTTP headers to send to the MCP server. Use for authentication + or other purposes. - The annotations of the text output. + - `require_approval: optional object { always, never } or "always" or "never"` - - `FileCitation object { file_id, filename, index, type }` + Specify which of the MCP server's tools require approval. - A citation to a file. + - `McpToolApprovalFilter object { always, never }` - - `file_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 ID of the file. + - `always: optional object { read_only, tool_names }` - - `filename: string` + A filter object to specify which tools are allowed. - The filename of the file cited. + - `read_only: optional boolean` - - `index: number` + 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 index of the file in the list of files. + - `tool_names: optional array of string` - - `type: "file_citation"` + List of allowed tool names. - The type of the file citation. Always `file_citation`. + - `never: optional object { read_only, tool_names }` - - `"file_citation"` + A filter object to specify which tools are allowed. - - `URLCitation object { end_index, start_index, title, 2 more }` + - `read_only: optional boolean` - A citation for a web resource used to generate a model response. + 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. - - `end_index: number` + - `tool_names: optional array of string` - The index of the last character of the URL citation in the message. + List of allowed tool names. - - `start_index: number` + - `McpToolApprovalSetting = "always" or "never"` - The index of the first character of the URL citation in the message. + 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. - - `title: string` + - `"always"` - The title of the web resource. + - `"never"` - - `type: "url_citation"` + - `server_description: optional string` - The type of the URL citation. Always `url_citation`. + Optional description of the MCP server, used to provide more context. - - `"url_citation"` + - `server_url: optional string` - - `url: string` + The URL for the MCP server. One of `server_url`, `connector_id`, or + `tunnel_id` must be provided. - The URL of the web resource. + - `tunnel_id: optional string` - - `ContainerFileCitation object { container_id, end_index, file_id, 3 more }` + The Secure MCP Tunnel ID to use instead of a direct server URL. One of + `server_url`, `connector_id`, or `tunnel_id` must be provided. - A citation for a container file used to generate a model response. + - `CodeInterpreter object { container, type, allowed_callers }` - - `container_id: string` + A tool that runs Python code to help generate a response to a prompt. - The ID of the container file. + - `container: string or object { type, file_ids, memory_limit, network_policy }` - - `end_index: number` + 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 index of the last character of the container file citation in the message. + - `string` - - `file_id: string` + The container ID. - The ID of the file. + - `CodeInterpreterToolAuto object { type, file_ids, memory_limit, network_policy }` - - `filename: string` + Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. - The filename of the container file cited. + - `type: "auto"` - - `start_index: number` + Always `auto`. - The index of the first character of the container file citation in the message. + - `"auto"` - - `type: "container_file_citation"` + - `file_ids: optional array of string` - The type of the container file citation. Always `container_file_citation`. + An optional list of uploaded files to make available to your code. - - `"container_file_citation"` + - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` - - `FilePath object { file_id, index, type }` + The memory limit for the code interpreter container. - A path to a file. + - `"1g"` - - `file_id: string` + - `"4g"` - The ID of the file. + - `"16g"` - - `index: number` + - `"64g"` - The index of the file in the list of files. + - `network_policy: optional ContainerNetworkPolicyDisabled or ContainerNetworkPolicyAllowlist` - - `type: "file_path"` + Network access policy for the container. - The type of the file path. Always `file_path`. + - `ContainerNetworkPolicyDisabled object { type }` - - `"file_path"` + - `ContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` - - `logprobs: array of object { token, bytes, logprob, top_logprobs }` + - `type: "code_interpreter"` - - `token: string` + The type of the code interpreter tool. Always `code_interpreter`. - - `bytes: array of number` + - `"code_interpreter"` - - `logprob: number` + - `allowed_callers: optional array of "direct" or "programmatic"` - - `top_logprobs: array of object { token, bytes, logprob }` + The tool invocation context(s). - - `token: string` + - `"direct"` - - `bytes: array of number` + - `"programmatic"` - - `logprob: number` + - `ProgrammaticToolCalling object { type }` - - `text: string` + - `type: "programmatic_tool_calling"` - The text output from the model. + The type of the tool. Always `programmatic_tool_calling`. - - `type: "output_text"` + - `"programmatic_tool_calling"` - The type of the output text. Always `output_text`. + - `ImageGeneration object { type, action, background, 9 more }` - - `"output_text"` + A tool that generates images using the GPT image models. - - `ResponseOutputRefusal object { refusal, type }` + - `type: "image_generation"` - A refusal from the model. + The type of the image generation tool. Always `image_generation`. - - `refusal: string` + - `"image_generation"` - The refusal explanation from the model. + - `action: optional "generate" or "edit" or "auto"` - - `type: "refusal"` + Whether to generate a new image or edit an existing image. Default: `auto`. - The type of the refusal. Always `refusal`. + - `"generate"` - - `"refusal"` + - `"edit"` - - `role: "assistant"` + - `"auto"` - The role of the output message. Always `assistant`. + - `background: optional "transparent" or "opaque" or "auto"` - - `"assistant"` + 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 message input. One of `in_progress`, `completed`, or - `incomplete`. Populated when input 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: "message"` + - `"high"` - The type of the output message. Always `message`. + - `"low"` - - `"message"` + - `input_image_mask: optional object { file_id, image_url }` - - `phase: optional "commentary" or "final_answer"` + Optional mask for inpainting. Contains `image_url` + (string, optional) and `file_id` (string, optional). - 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. + - `file_id: optional string` - - `"commentary"` + File ID for the mask image. - - `"final_answer"` + - `image_url: optional string` - - `FileSearchCall object { id, queries, status, 2 more }` + Base64-encoded mask image. - The results of a file search tool call. See the - [file search guide](/docs/guides/tools-file-search) for more information. + - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` - - `id: string` + The image generation model to use. Default: `gpt-image-1`. - The unique ID of the file search tool call. + - `string` - - `queries: array of string` + - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` - The queries used to search for files. + The image generation model to use. Default: `gpt-image-1`. - - `status: "in_progress" or "searching" or "completed" or 2 more` + - `"gpt-image-1"` - The status of the file search tool call. One of `in_progress`, - `searching`, `incomplete` or `failed`, + - `"gpt-image-1-mini"` - - `"in_progress"` + - `"gpt-image-1.5"` - - `"searching"` + - `moderation: optional "auto" or "low"` - - `"completed"` + Moderation level for the generated image. Default: `auto`. - - `"incomplete"` + - `"auto"` - - `"failed"` + - `"low"` - - `type: "file_search_call"` + - `output_compression: optional number` - The type of the file search tool call. Always `file_search_call`. + Compression level for the output image. Default: 100. - - `"file_search_call"` + - `output_format: optional "png" or "webp" or "jpeg"` - - `results: optional array of object { attributes, file_id, filename, 2 more }` + The output format of the generated image. One of `png`, `webp`, or + `jpeg`. Default: `png`. - The results of the file search tool call. + - `"png"` - - `attributes: optional map[string or number or boolean]` + - `"webp"` - 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. + - `"jpeg"` - - `string` + - `partial_images: optional number` - - `number` + Number of partial images to generate in streaming mode, from 0 (default value) to 3. - - `boolean` + - `quality: optional "low" or "medium" or "high" or "auto"` - - `file_id: optional string` + The quality of the generated image. One of `low`, `medium`, `high`, + or `auto`. Default: `auto`. - The unique ID of the file. + - `"low"` - - `filename: optional string` + - `"medium"` - The name of the file. + - `"high"` - - `score: optional number` + - `"auto"` - The relevance score of the file - a value between 0 and 1. + - `size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or "auto"` - - `text: 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 text that was retrieved from the file. + - `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, allowed_callers, 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"` + - `allowed_callers: optional array of "direct" or "programmatic"` - - `"completed"` + The tool invocation context(s). - - `"incomplete"` + - `"direct"` - - `type: "computer_call"` + - `"programmatic"` - The type of the computer call. Always `computer_call`. + - `environment: optional ContainerAuto or LocalEnvironment or ContainerReference` - - `"computer_call"` + - `ContainerAuto object { type, file_ids, memory_limit, 2 more }` - - `action: optional ComputerAction` + - `LocalEnvironment object { type, skills }` - A click action. + - `ContainerReference object { container_id, type }` - - `Click object { button, type, x, 2 more }` + - `Custom object { name, type, allowed_callers, 3 more }` - A click action. + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) - - `button: "left" or "right" or "wheel" or 2 more` + - `name: string` - Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. + The name of the custom tool, used to identify it in tool calls. - - `"left"` + - `type: "custom"` - - `"right"` + The type of the custom tool. Always `custom`. - - `"wheel"` + - `"custom"` - - `"back"` + - `allowed_callers: optional array of "direct" or "programmatic"` - - `"forward"` + The tool invocation context(s). - - `type: "click"` + - `"direct"` - Specifies the event type. For a click action, this property is always `click`. + - `"programmatic"` - - `"click"` + - `defer_loading: optional boolean` - - `x: number` + Whether this tool should be deferred and discovered via tool search. - The x-coordinate where the click occurred. + - `description: optional string` - - `y: number` + Optional description of the custom tool, used to provide more context. - The y-coordinate where the click occurred. + - `format: optional CustomToolInputFormat` - - `keys: optional array of string` + The input format for the custom tool. Default is unconstrained text. - The keys being held while clicking. + - `Namespace object { description, name, tools, type }` - - `DoubleClick object { keys, type, x, y }` + Groups function/custom tools under a shared namespace. - A double click action. + - `description: string` - - `keys: array of string` + A description of the namespace shown to the model. - The keys being held while double-clicking. + - `name: string` - - `type: "double_click"` + The namespace name used in tool calls (for example, `crm`). - Specifies the event type. For a double click action, this property is always set to `double_click`. + - `tools: array of object { name, type, allowed_callers, 5 more } or object { name, type, allowed_callers, 3 more }` - - `"double_click"` + The function/custom tools available inside this namespace. - - `x: number` + - `Function object { name, type, allowed_callers, 5 more }` - The x-coordinate where the double click occurred. + - `name: string` - - `y: number` + - `type: "function"` - The y-coordinate where the double click occurred. + - `"function"` - - `Drag object { path, type, keys }` + - `allowed_callers: optional array of "direct" or "programmatic"` - A drag action. + The tool invocation context(s). - - `path: array of object { x, y }` + - `"direct"` - An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg + - `"programmatic"` - ``` - [ - { x: 100, y: 200 }, - { x: 200, y: 300 } - ] - ``` + - `defer_loading: optional boolean` - - `x: number` + Whether this function should be deferred and discovered via tool search. - The x-coordinate. + - `description: optional string` - - `y: number` + - `output_schema: optional map[unknown]` - The y-coordinate. + A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. - - `type: "drag"` + - `parameters: optional unknown` - Specifies the event type. For a drag action, this property is always set to `drag`. + - `strict: optional boolean` - - `"drag"` + Whether to enforce strict parameter validation. If omitted, Responses attempts to use strict validation when the schema is compatible, and falls back to non-strict validation otherwise. - - `keys: optional array of string` + - `Custom object { name, type, allowed_callers, 3 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`. + - `allowed_callers: optional array of "direct" or "programmatic"` - - `"keypress"` + The tool invocation context(s). - - `Move object { type, x, y, keys }` + - `"direct"` - A mouse move action. + - `"programmatic"` - - `type: "move"` + - `defer_loading: optional boolean` - Specifies the event type. For a move action, this property is always set to `move`. + Whether this tool should be deferred and discovered via tool search. - - `"move"` + - `description: optional string` - - `x: number` + Optional description of the custom tool, used to provide more context. - The x-coordinate to move to. + - `format: optional CustomToolInputFormat` - - `y: number` + The input format for the custom tool. Default is unconstrained text. - The y-coordinate to move to. + - `type: "namespace"` - - `keys: optional array of string` + The type of the tool. Always `namespace`. - The keys being held while moving the mouse. + - `"namespace"` - - `Screenshot object { type }` + - `ToolSearch object { type, description, execution, parameters }` - A screenshot action. + Hosted or BYOT tool search configuration for deferred tools. - - `type: "screenshot"` + - `type: "tool_search"` - Specifies the event type. For a screenshot action, this property is always set to `screenshot`. + The type of the tool. Always `tool_search`. - - `"screenshot"` + - `"tool_search"` - - `Scroll object { scroll_x, scroll_y, type, 3 more }` + - `description: optional string` - A scroll action. + Description shown to the model for a client-executed tool search tool. - - `scroll_x: number` + - `execution: optional "server" or "client"` - The horizontal scroll distance. + Whether tool search is executed by the server or by the client. - - `scroll_y: number` + - `"server"` - The vertical scroll distance. + - `"client"` - - `type: "scroll"` + - `parameters: optional unknown` - Specifies the event type. For a scroll action, this property is always set to `scroll`. + Parameter schema for a client-executed tool search tool. - - `"scroll"` + - `WebSearchPreview object { type, search_content_types, search_context_size, user_location }` - - `x: number` + This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - The x-coordinate where the scroll occurred. + - `type: "web_search_preview" or "web_search_preview_2025_03_11"` - - `y: number` + The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. - The y-coordinate where the scroll occurred. + - `"web_search_preview"` - - `keys: optional array of string` + - `"web_search_preview_2025_03_11"` - The keys being held while scrolling. + - `search_content_types: optional array of "text" or "image"` - - `Type object { text, type }` + - `"text"` - An action to type in text. + - `"image"` - - `text: string` + - `search_context_size: optional "low" or "medium" or "high"` - The text to type. + 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: "type"` + - `"low"` - Specifies the event type. For a type action, this property is always set to `type`. + - `"medium"` - - `"type"` + - `"high"` - - `Wait object { type }` + - `user_location: optional object { type, city, country, 2 more }` - A wait action. + The user's location. - - `type: "wait"` + - `type: "approximate"` - Specifies the event type. For a wait action, this property is always set to `wait`. + The type of location approximation. Always `approximate`. - - `"wait"` + - `"approximate"` - - `actions: optional ComputerActionList` + - `city: optional string` - Flattened batched actions for `computer_use`. Each action includes an - `type` discriminator and action-specific fields. + Free text input for the city of the user, e.g. `San Francisco`. - - `Click object { button, type, x, 2 more }` + - `country: optional string` - A click action. + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - - `DoubleClick object { keys, type, x, y }` + - `region: optional string` - A double click action. + Free text input for the region of the user, e.g. `California`. - - `Drag object { path, type, keys }` + - `timezone: optional string` - A drag action. + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - - `Keypress object { keys, type }` + - `ApplyPatch object { type, allowed_callers }` - A collection of keypresses the model would like to perform. + Allows the assistant to create, delete, or update files using unified diffs. - - `Move object { type, x, y, keys }` + - `type: "apply_patch"` - A mouse move action. + The type of the tool. Always `apply_patch`. - - `Screenshot object { type }` + - `"apply_patch"` - A screenshot action. + - `allowed_callers: optional array of "direct" or "programmatic"` - - `Scroll object { scroll_x, scroll_y, type, 3 more }` + The tool invocation context(s). - A scroll action. + - `"direct"` - - `Type object { text, type }` + - `"programmatic"` - An action to type in text. + - `type: "additional_tools"` - - `Wait object { type }` + The type of the item. Always `additional_tools`. - A wait action. + - `"additional_tools"` - - `ComputerCallOutput object { call_id, output, type, 3 more }` + - `Compaction object { id, encrypted_content, type, created_by }` - The output of a computer tool call. + A compaction item generated by the [`v1/responses/compact` API](/docs/api-reference/responses/compact). - - `call_id: string` + - `id: string` - The ID of the computer tool call that produced the output. + The unique ID of the compaction item. - - `output: ResponseComputerToolCallOutputScreenshot` + - `encrypted_content: string` - A computer screenshot image used with the computer use tool. + The encrypted content that was produced by compaction. - - `type: "computer_screenshot"` + - `type: "compaction"` - Specifies the event type. For a computer screenshot, this property is - always set to `computer_screenshot`. + The type of the item. Always `compaction`. - - `"computer_screenshot"` + - `"compaction"` - - `file_id: optional string` + - `created_by: optional string` - The identifier of an uploaded file that contains the screenshot. + The identifier of the actor that created the item. - - `image_url: optional string` + - `ImageGenerationCall object { id, result, status, type }` - The URL of the screenshot image. + An image generation request made by the model. - - `type: "computer_call_output"` + - `id: string` - The type of the computer tool call output. Always `computer_call_output`. + The unique ID of the image generation call. - - `"computer_call_output"` + - `result: string` - - `id: optional string` + The generated image encoded in base64. - The ID of the computer tool call output. + - `status: "in_progress" or "completed" or "generating" or "failed"` - - `acknowledged_safety_checks: optional array of object { id, code, message }` + The status of the image generation call. - The safety checks reported by the API that have been acknowledged by the developer. + - `"in_progress"` - - `id: string` + - `"completed"` - The ID of the pending safety check. + - `"generating"` - - `code: optional string` + - `"failed"` - The type of the pending safety check. + - `type: "image_generation_call"` - - `message: optional string` + The type of the image generation call. Always `image_generation_call`. - Details about the pending safety check. + - `"image_generation_call"` - - `status: optional "in_progress" or "completed" or "incomplete"` + - `CodeInterpreterCall object { id, code, container_id, 3 more }` - The status of the message input. One of `in_progress`, `completed`, or `incomplete`. Populated when input items are returned via API. + A tool call to run code. - - `"in_progress"` + - `id: string` - - `"completed"` + The unique ID of the code interpreter tool call. - - `"incomplete"` + - `code: string` - - `WebSearchCall object { id, action, status, type }` + The code to run, or null if not available. - The results of a web search tool call. See the - [web search guide](/docs/guides/tools-web-search) for more information. + - `container_id: string` - - `id: string` + The ID of the container used to run the code. - The unique ID of the web search tool call. + - `outputs: array of object { logs, type } or object { type, url }` - - `action: object { type, queries, query, sources } or object { type, url } or object { pattern, type, url }` + The outputs generated by the code interpreter, such as logs or images. + Can be null if no outputs are available. - 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). + - `Logs object { logs, type }` - - `Search object { type, queries, query, sources }` + The logs output from the code interpreter. - Action type "search" - Performs a web search query. + - `logs: string` - - `type: "search"` + The logs output from the code interpreter. - The action type. + - `type: "logs"` - - `"search"` + The type of the output. Always `logs`. - - `queries: optional array of string` + - `"logs"` - The search queries. + - `Image object { type, url }` - - `query: optional string` + The image output from the code interpreter. - The search query. + - `type: "image"` - - `sources: optional array of object { type, url }` + The type of the output. Always `image`. - The sources used in the search. + - `"image"` - - `type: "url"` + - `url: string` - The type of source. Always `url`. + The URL of the image output from the code interpreter. - - `"url"` + - `status: "in_progress" or "completed" or "incomplete" or 2 more` - - `url: string` + The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. - The URL of the source. + - `"in_progress"` - - `OpenPage object { type, url }` + - `"completed"` - Action type "open_page" - Opens a specific URL from search results. + - `"incomplete"` - - `type: "open_page"` + - `"interpreting"` - The action type. + - `"failed"` - - `"open_page"` + - `type: "code_interpreter_call"` - - `url: optional string` + The type of the code interpreter tool call. Always `code_interpreter_call`. - The URL opened by the model. + - `"code_interpreter_call"` - - `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. + - `LocalShellCall object { id, action, call_id, 2 more }` - - `type: "find_in_page"` + A tool call to run a command on the local shell. - The action type. + - `id: string` - - `"find_in_page"` + The unique ID of the local shell call. - - `url: string` + - `action: object { command, env, type, 3 more }` - The URL of the page searched for the pattern. + Execute a shell command on the server. - - `status: "in_progress" or "searching" or "completed" or "failed"` + - `command: array of string` - The status of the web search tool call. + The command to run. - - `"in_progress"` + - `env: map[string]` - - `"searching"` + Environment variables to set for the command. - - `"completed"` + - `type: "exec"` - - `"failed"` + The type of the local shell action. Always `exec`. - - `type: "web_search_call"` + - `"exec"` - The type of the web search tool call. Always `web_search_call`. + - `timeout_ms: optional number` - - `"web_search_call"` + Optional timeout in milliseconds for the command. - - `FunctionCall object { arguments, call_id, name, 5 more }` + - `user: optional string` - A tool call to run a function. See the - [function calling guide](/docs/guides/function-calling) for more information. + Optional user to run the command as. - - `arguments: string` + - `working_directory: optional string` - A JSON string of the arguments to pass to the function. + Optional working directory to run the command in. - `call_id: string` - The unique ID of the function tool call generated by the model. - - - `name: string` - - The name of the function to run. + The unique ID of the local shell tool call generated by the model. - - `type: "function_call"` + - `status: "in_progress" or "completed" or "incomplete"` - The type of the function tool call. Always `function_call`. + The status of the local shell call. - - `"function_call"` + - `"in_progress"` - - `id: optional string` + - `"completed"` - The unique ID of the function tool call. + - `"incomplete"` - - `caller: optional object { type } or object { caller_id, type }` + - `type: "local_shell_call"` - The execution context that produced this tool call. + The type of the local shell call. Always `local_shell_call`. - - `Direct object { type }` + - `"local_shell_call"` - - `type: "direct"` + - `LocalShellCallOutput object { id, output, type, status }` - - `"direct"` + The output of a local shell tool call. - - `Program object { caller_id, type }` + - `id: string` - - `caller_id: string` + The unique ID of the local shell tool call generated by the model. - The call ID of the program item that produced this tool call. + - `output: string` - - `type: "program"` + A JSON string of the output of the local shell tool call. - - `"program"` + - `type: "local_shell_call_output"` - - `namespace: optional string` + The type of the local shell tool call output. Always `local_shell_call_output`. - The namespace of the function to run. + - `"local_shell_call_output"` - `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. + The status of the item. One of `in_progress`, `completed`, or `incomplete`. - `"in_progress"` @@ -6807,145 +6844,173 @@ as input for the model's response. - `"incomplete"` - - `FunctionCallOutput object { call_id, output, type, 3 more }` + - `ShellCall object { id, action, call_id, 5 more }` - The output of a function tool call. + A tool call that executes one or more shell commands in a managed environment. + + - `id: string` + + The unique ID of the shell tool call. Populated when this item is returned via API. + + - `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` + + - `max_output_length: number` + + Optional maximum number of characters to return from each command. + + - `timeout_ms: number` + + Optional timeout in milliseconds for the commands. - `call_id: string` - The unique ID of the function tool call generated by the model. + The unique ID of the shell tool call generated by the model. - - `output: string or array of ResponseInputTextContent or ResponseInputImageContent or ResponseInputFileContent` + - `environment: ResponseLocalEnvironment or ResponseContainerReference` - Text, image, or file output of the function tool call. + Represents the use of a local environment to perform shell actions. - - `string` + - `ResponseLocalEnvironment object { type }` - A JSON string of the output of the function tool call. + Represents the use of a local environment to perform shell actions. - - `array of ResponseInputTextContent or ResponseInputImageContent or ResponseInputFileContent` + - `type: "local"` - An array of content outputs (text, image, file) for the function tool call. + The environment type. Always `local`. - - `ResponseInputTextContent object { text, type, prompt_cache_breakpoint }` + - `"local"` - A text input to the model. + - `ResponseContainerReference object { container_id, type }` - - `text: string` + Represents a container created with /v1/containers. - The text input to the model. + - `container_id: string` - - `type: "input_text"` + - `type: "container_reference"` - The type of the input item. Always `input_text`. + The environment type. Always `container_reference`. - - `"input_text"` + - `"container_reference"` - - `prompt_cache_breakpoint: optional object { mode }` + - `status: "in_progress" or "completed" or "incomplete"` - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. - - `mode: "explicit"` + - `"in_progress"` - The breakpoint mode. Always `explicit`. + - `"completed"` - - `"explicit"` + - `"incomplete"` - - `ResponseInputImageContent object { type, detail, file_id, 2 more }` + - `type: "shell_call"` - An image input to the model. Learn about [image inputs](/docs/guides/vision) + The type of the item. Always `shell_call`. - - `type: "input_image"` + - `"shell_call"` - The type of the input item. Always `input_image`. + - `caller: optional object { type } or object { caller_id, type }` - - `"input_image"` + The execution context that produced this tool call. - - `detail: optional "low" or "high" or "auto" or "original"` + - `Direct object { type }` - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + - `type: "direct"` - - `"low"` + - `"direct"` - - `"high"` + - `Program object { caller_id, type }` - - `"auto"` + - `caller_id: string` - - `"original"` + The call ID of the program item that produced this tool call. - - `file_id: optional string` + - `type: "program"` - The ID of the file to be sent to the model. + - `"program"` - - `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 ID of the entity that created this tool call. - - `prompt_cache_breakpoint: optional object { mode }` + - `ShellCallOutput object { id, call_id, max_output_length, 5 more }` - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + The output of a shell tool call that was emitted. - - `mode: "explicit"` + - `id: string` - The breakpoint mode. Always `explicit`. + The unique ID of the shell call output. Populated when this item is returned via API. - - `"explicit"` + - `call_id: string` - - `ResponseInputFileContent object { type, detail, file_data, 4 more }` + The unique ID of the shell tool call generated by the model. - A file input to the model. + - `max_output_length: number` - - `type: "input_file"` + The maximum length of the shell command output. This is generated by the model and should be passed back with the raw output. - The type of the input item. Always `input_file`. + - `output: array of object { outcome, stderr, stdout, created_by }` - - `"input_file"` + An array of shell call output contents - - `detail: optional "auto" or "low" or "high"` + - `outcome: object { type } or object { exit_code, type }` - The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. + Represents either an exit outcome (with an exit code) or a timeout outcome for a shell call output chunk. - - `"auto"` + - `Timeout object { type }` - - `"low"` + Indicates that the shell call exceeded its configured time limit. - - `"high"` + - `type: "timeout"` - - `file_data: optional string` + The outcome type. Always `timeout`. - The base64-encoded data of the file to be sent to the model. + - `"timeout"` - - `file_id: optional string` + - `Exit object { exit_code, type }` - The ID of the file to be sent to the model. + Indicates that the shell commands finished and returned an exit code. - - `file_url: optional string` + - `exit_code: number` - The URL of the file to be sent to the model. + Exit code from the shell process. - - `filename: optional string` + - `type: "exit"` - The name of the file to be sent to the model. + The outcome type. Always `exit`. - - `prompt_cache_breakpoint: optional object { mode }` + - `"exit"` - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + - `stderr: string` - - `mode: "explicit"` + The standard error output that was captured. - The breakpoint mode. Always `explicit`. + - `stdout: string` - - `"explicit"` + The standard output that was captured. - - `type: "function_call_output"` + - `created_by: optional string` - The type of the function tool call output. Always `function_call_output`. + The identifier of the actor that created the item. - - `"function_call_output"` + - `status: "in_progress" or "completed" or "incomplete"` - - `id: optional string` + The status of the shell call output. One of `in_progress`, `completed`, or `incomplete`. - The unique ID of the function tool call output. Populated when this item is returned via API. + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `type: "shell_call_output"` + + The type of the shell call output. Always `shell_call_output`. + + - `"shell_call_output"` - `caller: optional object { type } or object { caller_id, type }` @@ -6955,8 +7020,6 @@ as input for the model's response. - `type: "direct"` - The caller type. Always `direct`. - - `"direct"` - `Program object { caller_id, type }` @@ -6967,1251 +7030,731 @@ as input for the model's response. - `type: "program"` - The caller type. Always `program`. - - `"program"` - - `status: optional "in_progress" or "completed" or "incomplete"` + - `created_by: optional string` - The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. + The identifier of the actor that created the item. - - `"in_progress"` + - `ApplyPatchCall object { id, call_id, operation, 4 more }` - - `"completed"` + A tool call that applies file diffs by creating, deleting, or updating files. - - `"incomplete"` + - `id: string` - - `ToolSearchCall object { arguments, type, id, 3 more }` + The unique ID of the apply patch tool call. Populated when this item is returned via API. - - `arguments: unknown` + - `call_id: string` - The arguments supplied to the tool search call. + The unique ID of the apply patch tool call generated by the model. - - `type: "tool_search_call"` + - `operation: object { diff, path, type } or object { path, type } or object { diff, path, type }` - The item type. Always `tool_search_call`. + One of the create_file, delete_file, or update_file operations applied via apply_patch. - - `"tool_search_call"` + - `CreateFile object { diff, path, type }` - - `id: optional string` + Instruction describing how to create a file via the apply_patch tool. - The unique ID of this tool search call. + - `diff: string` - - `call_id: optional string` + Diff to apply. - The unique ID of the tool search call generated by the model. + - `path: string` - - `execution: optional "server" or "client"` + Path of the file to create. - Whether tool search was executed by the server or by the client. + - `type: "create_file"` - - `"server"` + Create a new file with the provided diff. - - `"client"` + - `"create_file"` - - `status: optional "in_progress" or "completed" or "incomplete"` + - `DeleteFile object { path, type }` - The status of the tool search call. + Instruction describing how to delete a file via the apply_patch tool. - - `"in_progress"` + - `path: string` - - `"completed"` + Path of the file to delete. - - `"incomplete"` + - `type: "delete_file"` - - `ToolSearchOutput object { tools, type, id, 3 more }` + Delete the specified file. - - `tools: array of object { name, parameters, strict, 5 more } or object { type, vector_store_ids, filters, 2 more } or object { type } or 13 more` + - `"delete_file"` - The loaded tool definitions returned by the tool search output. + - `UpdateFile object { diff, path, type }` - - `Function object { name, parameters, strict, 5 more }` + Instruction describing how to update a file via the apply_patch tool. - 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). + - `diff: string` - - `name: string` + Diff to apply. - The name of the function to call. + - `path: string` - - `parameters: map[unknown]` + Path of the file to update. - A JSON schema object describing the parameters of the function. + - `type: "update_file"` - - `strict: boolean` + Update an existing file with the provided diff. - Whether strict parameter validation is enforced for this function tool. + - `"update_file"` - - `type: "function"` + - `status: "in_progress" or "completed"` - The type of the function tool. Always `function`. + The status of the apply patch tool call. One of `in_progress` or `completed`. - - `"function"` + - `"in_progress"` - - `allowed_callers: optional array of "direct" or "programmatic"` + - `"completed"` - The tool invocation context(s). + - `type: "apply_patch_call"` - - `"direct"` + The type of the item. Always `apply_patch_call`. - - `"programmatic"` + - `"apply_patch_call"` - - `defer_loading: optional boolean` + - `caller: optional object { type } or object { caller_id, type }` - Whether this function is deferred and loaded via tool search. + The execution context that produced this tool call. - - `description: optional string` + - `Direct object { type }` - A description of the function. Used by the model to determine whether or not to call the function. + - `type: "direct"` - - `output_schema: optional map[unknown]` + - `"direct"` - A JSON schema object describing the JSON value encoded in string outputs for this function. + - `Program object { caller_id, type }` - - `FileSearch object { type, vector_store_ids, filters, 2 more }` + - `caller_id: 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 call ID of the program item that produced this tool call. - - `type: "file_search"` + - `type: "program"` - The type of the file search tool. Always `file_search`. + - `"program"` - - `"file_search"` + - `created_by: optional string` - - `vector_store_ids: array of string` + The ID of the entity that created this tool call. - The IDs of the vector stores to search. + - `ApplyPatchCallOutput object { id, call_id, status, 4 more }` - - `filters: optional ComparisonFilter or CompoundFilter` + The output emitted by an apply patch tool call. - A filter to apply. + - `id: string` - - `ComparisonFilter object { key, type, value }` + The unique ID of the apply patch tool call output. Populated when this item is returned via API. - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + - `call_id: string` - - `key: string` + The unique ID of the apply patch tool call generated by the model. - The key to compare against the value. + - `status: "completed" or "failed"` - - `type: "eq" or "ne" or "gt" or 5 more` + The status of the apply patch tool call output. One of `completed` or `failed`. - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + - `"completed"` - - `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 + - `"failed"` - - `"eq"` + - `type: "apply_patch_call_output"` - - `"ne"` + The type of the item. Always `apply_patch_call_output`. - - `"gt"` + - `"apply_patch_call_output"` - - `"gte"` + - `caller: optional object { type } or object { caller_id, type }` - - `"lt"` + The execution context that produced this tool call. - - `"lte"` + - `Direct object { type }` - - `"in"` + - `type: "direct"` - - `"nin"` + - `"direct"` - - `value: string or number or boolean or array of string or number` + - `Program object { caller_id, type }` - The value to compare against the attribute key; supports string, number, or boolean types. + - `caller_id: string` - - `string` + The call ID of the program item that produced this tool call. - - `number` + - `type: "program"` - - `boolean` + - `"program"` - - `array of string or number` + - `created_by: optional string` - - `string` + The ID of the entity that created this tool call output. - - `number` + - `output: optional string` - - `CompoundFilter object { filters, type }` + Optional textual output returned by the apply patch tool. - Combine multiple filters using `and` or `or`. + - `McpCall object { id, arguments, name, 6 more }` - - `filters: array of ComparisonFilter or unknown` + An invocation of a tool on an MCP server. - Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. + - `id: string` - - `ComparisonFilter object { key, type, value }` + The unique ID of the tool call. - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + - `arguments: string` - - `unknown` + A JSON string of the arguments passed to the tool. - - `type: "and" or "or"` + - `name: string` - Type of operation: `and` or `or`. + The name of the tool that was run. - - `"and"` + - `server_label: string` - - `"or"` + The label of the MCP server running the tool. - - `max_num_results: optional number` + - `type: "mcp_call"` - The maximum number of results to return. This number should be between 1 and 50 inclusive. + The type of the item. Always `mcp_call`. - - `ranking_options: optional object { hybrid_search, ranker, score_threshold }` + - `"mcp_call"` - Ranking options for search. + - `approval_request_id: optional string` - - `hybrid_search: optional object { embedding_weight, text_weight }` + 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. - Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. + - `error: optional string` - - `embedding_weight: number` + The error from the tool call, if any. - The weight of the embedding in the reciprocal ranking fusion. + - `output: optional string` - - `text_weight: number` + The output from the tool call. - The weight of the text in the reciprocal ranking fusion. + - `status: optional "in_progress" or "completed" or "incomplete" or 2 more` - - `ranker: optional "auto" or "default-2024-11-15"` + The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. - The ranker to use for the file search. + - `"in_progress"` - - `"auto"` + - `"completed"` - - `"default-2024-11-15"` + - `"incomplete"` - - `score_threshold: optional number` + - `"calling"` - 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. + - `"failed"` - - `Computer object { type }` + - `McpListTools object { id, server_label, tools, 2 more }` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + A list of tools available on an MCP server. - - `type: "computer"` + - `id: string` - The type of the computer tool. Always `computer`. + The unique ID of the list. - - `"computer"` + - `server_label: string` - - `ComputerUsePreview object { display_height, display_width, environment, type }` + The label of the MCP server. - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `tools: array of object { input_schema, name, annotations, description }` - - `display_height: number` + The tools available on the server. - The height of the computer display. + - `input_schema: unknown` - - `display_width: number` + The JSON schema describing the tool's input. - The width of the computer display. + - `name: string` - - `environment: "windows" or "mac" or "linux" or 2 more` + The name of the tool. - The type of computer environment to control. + - `annotations: optional unknown` - - `"windows"` + Additional annotations about the tool. - - `"mac"` + - `description: optional string` - - `"linux"` + The description of the tool. - - `"ubuntu"` - - - `"browser"` - - - `type: "computer_use_preview"` + - `type: "mcp_list_tools"` - The type of the computer use tool. Always `computer_use_preview`. + The type of the item. Always `mcp_list_tools`. - - `"computer_use_preview"` + - `"mcp_list_tools"` - - `WebSearch object { type, filters, search_context_size, user_location }` + - `error: optional string` - Search the Internet for sources related to the prompt. Learn more about the - [web search tool](/docs/guides/tools-web-search). + Error message if the server could not list tools. - - `type: "web_search" or "web_search_2025_08_26"` + - `McpApprovalRequest object { id, arguments, name, 2 more }` - The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. + A request for human approval of a tool invocation. - - `"web_search"` + - `id: string` - - `"web_search_2025_08_26"` + The unique ID of the approval request. - - `filters: optional object { allowed_domains }` + - `arguments: string` - Filters for the search. + A JSON string of arguments for the tool. - - `allowed_domains: optional array of string` + - `name: string` - Allowed domains for the search. If not provided, all domains are allowed. - Subdomains of the provided domains are allowed as well. + The name of the tool to run. - Example: `["pubmed.ncbi.nlm.nih.gov"]` + - `server_label: string` - - `search_context_size: optional "low" or "medium" or "high"` + The label of the MCP server making the request. - 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: "mcp_approval_request"` - - `"low"` + The type of the item. Always `mcp_approval_request`. - - `"medium"` + - `"mcp_approval_request"` - - `"high"` + - `McpApprovalResponse object { id, approval_request_id, approve, 2 more }` - - `user_location: optional object { city, country, region, 2 more }` + A response to an MCP approval request. - The approximate location of the user. + - `id: string` - - `city: optional string` + The unique ID of the approval response - Free text input for the city of the user, e.g. `San Francisco`. + - `approval_request_id: string` - - `country: optional string` + The ID of the approval request being answered. - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + - `approve: boolean` - - `region: optional string` + Whether the request was approved. - Free text input for the region of the user, e.g. `California`. + - `type: "mcp_approval_response"` - - `timezone: optional string` + The type of the item. Always `mcp_approval_response`. - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + - `"mcp_approval_response"` - - `type: optional "approximate"` + - `reason: optional string` - The type of location approximation. Always `approximate`. + Optional reason for the decision. - - `"approximate"` + - `CustomToolCall object { call_id, input, name, 4 more }` - - `Mcp object { server_label, type, allowed_callers, 9 more }` + A call to a custom tool created by the model. - Give the model access to additional tools via remote Model Context Protocol - (MCP) servers. [Learn more about MCP](/docs/guides/tools-remote-mcp). + - `call_id: string` - - `server_label: string` + An identifier used to map this custom tool call to a tool call output. - A label for this MCP server, used to identify it in tool calls. + - `input: string` - - `type: "mcp"` + The input for the custom tool call generated by the model. - The type of the MCP tool. Always `mcp`. + - `name: string` - - `"mcp"` + The name of the custom tool being called. - - `allowed_callers: optional array of "direct" or "programmatic"` + - `type: "custom_tool_call"` - The tool invocation context(s). + The type of the custom tool call. Always `custom_tool_call`. - - `"direct"` + - `"custom_tool_call"` - - `"programmatic"` + - `id: optional string` - - `allowed_tools: optional array of string or object { read_only, tool_names }` + The unique ID of the custom tool call in the OpenAI platform. - List of allowed tool names or a filter object. + - `caller: optional object { type } or object { caller_id, type }` - - `McpAllowedTools = array of string` + The execution context that produced this tool call. - A string array of allowed tool names + - `Direct object { type }` - - `McpToolFilter object { read_only, tool_names }` + - `type: "direct"` - A filter object to specify which tools are allowed. + - `"direct"` - - `read_only: optional boolean` + - `Program object { caller_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. + - `caller_id: string` - - `tool_names: optional array of string` + The call ID of the program item that produced this tool call. - List of allowed tool names. + - `type: "program"` - - `authorization: optional string` + - `"program"` - 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. + - `namespace: optional string` - - `connector_id: optional "connector_dropbox" or "connector_gmail" or "connector_googlecalendar" or 5 more` + The namespace of the custom tool being called. - Identifier for service connectors, like those available in ChatGPT. One of - `server_url`, `connector_id`, or `tunnel_id` must be provided. Learn more - about service connectors [here](/docs/guides/tools-remote-mcp#connectors). + - `CustomToolCallOutput object { id, call_id, output, 4 more }` - Currently supported `connector_id` values are: + - `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` + The unique ID of the custom tool call output item. - - `"connector_dropbox"` + - `call_id: string` - - `"connector_gmail"` + The call ID, used to map this custom tool call output to a custom tool call. - - `"connector_googlecalendar"` + - `output: string or array of ResponseInputText or ResponseInputImage or ResponseInputFile` - - `"connector_googledrive"` + The output from the custom tool call generated by your code. + Can be a string or an list of output content. - - `"connector_microsoftteams"` + - `StringOutput = string` - - `"connector_outlookcalendar"` + A string of the output of the custom tool call. - - `"connector_outlookemail"` + - `OutputContentList = array of ResponseInputText or ResponseInputImage or ResponseInputFile` - - `"connector_sharepoint"` + Text, image, or file output of the custom tool call. - - `defer_loading: optional boolean` + - `ResponseInputText object { text, type, prompt_cache_breakpoint }` - Whether this MCP tool is deferred and discovered via tool search. + A text input to the model. - - `headers: optional map[string]` + - `ResponseInputImage object { detail, type, file_id, 2 more }` - Optional HTTP headers to send to the MCP server. Use for authentication - or other purposes. + An image input to the model. Learn about [image inputs](/docs/guides/vision). - - `require_approval: optional object { always, never } or "always" or "never"` + - `ResponseInputFile object { type, detail, file_data, 4 more }` - Specify which of the MCP server's tools require approval. + A file input to the model. - - `McpToolApprovalFilter object { always, never }` + - `status: "in_progress" or "completed" or "incomplete"` - 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 status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `always: optional object { read_only, tool_names }` + - `"in_progress"` - A filter object to specify which tools are allowed. + - `"completed"` - - `read_only: optional boolean` + - `"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. + - `type: "custom_tool_call_output"` - - `tool_names: optional array of string` + The type of the custom tool call output. Always `custom_tool_call_output`. - List of allowed tool names. + - `"custom_tool_call_output"` - - `never: optional object { read_only, tool_names }` + - `caller: optional object { type } or object { caller_id, type }` - A filter object to specify which tools are allowed. + The execution context that produced this tool call. - - `read_only: optional boolean` + - `Direct 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. + - `type: "direct"` - - `tool_names: optional array of string` + The caller type. Always `direct`. - List of allowed tool names. + - `"direct"` - - `McpToolApprovalSetting = "always" or "never"` + - `Program object { caller_id, type }` - Specify a single approval policy for all tools. One of `always` or - `never`. When set to `always`, all tools will require approval. When - set to `never`, all tools will not require approval. + - `caller_id: string` - - `"always"` + The call ID of the program item that produced this tool call. - - `"never"` + - `type: "program"` - - `server_description: optional string` + The caller type. Always `program`. - Optional description of the MCP server, used to provide more context. + - `"program"` - - `server_url: optional string` + - `created_by: optional string` - The URL for the MCP server. One of `server_url`, `connector_id`, or - `tunnel_id` must be provided. + The identifier of the actor that created the item. - - `tunnel_id: optional string` + - `parallel_tool_calls: boolean` - The Secure MCP Tunnel ID to use instead of a direct server URL. One of - `server_url`, `connector_id`, or `tunnel_id` must be provided. + Whether to allow the model to run tool calls in parallel. - - `CodeInterpreter object { container, type, allowed_callers }` + - `temperature: number` - A tool that runs Python code to help generate a response to a prompt. + What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. + We generally recommend altering this or `top_p` but not both. - - `container: string or object { type, file_ids, memory_limit, network_policy }` + - `tool_choice: ToolChoiceOptions or ToolChoiceAllowed or ToolChoiceTypes or 6 more` - 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. + How the model should select which tool (or tools) to use when generating + a response. See the `tools` parameter to see how to specify which tools + the model can call. - - `string` + - `ToolChoiceOptions = "none" or "auto" or "required"` - The container ID. + Controls which (if any) tool is called by the model. - - `CodeInterpreterToolAuto object { type, file_ids, memory_limit, network_policy }` + `none` means the model will not call any tool and instead generates a message. - Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. + `auto` means the model can pick between generating a message or calling one or + more tools. - - `type: "auto"` + `required` means the model must call one or more tools. - Always `auto`. + - `"none"` - `"auto"` - - `file_ids: optional array of string` - - An optional list of uploaded files to make available to your code. + - `"required"` - - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` + - `ToolChoiceAllowed object { mode, tools, type }` - The memory limit for the code interpreter container. + Constrains the tools available to the model to a pre-defined set. - - `"1g"` + - `mode: "auto" or "required"` - - `"4g"` + Constrains the tools available to the model to a pre-defined set. - - `"16g"` + `auto` allows the model to pick from among the allowed tools and generate a + message. - - `"64g"` + `required` requires the model to call one or more of the allowed tools. - - `network_policy: optional ContainerNetworkPolicyDisabled or ContainerNetworkPolicyAllowlist` + - `"auto"` - Network access policy for the container. + - `"required"` - - `ContainerNetworkPolicyDisabled object { type }` + - `tools: array of map[unknown]` - - `type: "disabled"` + A list of tool definitions that the model should be allowed to call. - Disable outbound network access. Always `disabled`. + For the Responses API, the list of tool definitions might look like: - - `"disabled"` + ```json + [ + { "type": "function", "name": "get_weather" }, + { "type": "mcp", "server_label": "deepwiki" }, + { "type": "image_generation" } + ] + ``` - - `ContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` + - `type: "allowed_tools"` - - `allowed_domains: array of string` + Allowed tool configuration type. Always `allowed_tools`. - A list of allowed domains when type is `allowlist`. + - `"allowed_tools"` - - `type: "allowlist"` + - `ToolChoiceTypes object { type }` - Allow outbound network access only to specified domains. Always `allowlist`. + Indicates that the model should use a built-in tool to generate a response. + [Learn more about built-in tools](/docs/guides/tools). - - `"allowlist"` + - `type: "file_search" or "web_search_preview" or "computer" or 5 more` - - `domain_secrets: optional array of ContainerNetworkPolicyDomainSecret` + The type of hosted tool the model should to use. Learn more about + [built-in tools](/docs/guides/tools). - Optional domain-scoped secrets for allowlisted domains. + Allowed values are: - - `domain: string` + - `file_search` + - `web_search_preview` + - `computer` + - `computer_use_preview` + - `computer_use` + - `code_interpreter` + - `image_generation` - The domain associated with the secret. + - `"file_search"` - - `name: string` + - `"web_search_preview"` - The name of the secret to inject for the domain. + - `"computer"` - - `value: string` + - `"computer_use_preview"` - The secret value to inject for the domain. + - `"computer_use"` - - `type: "code_interpreter"` + - `"web_search_preview_2025_03_11"` - The type of the code interpreter tool. Always `code_interpreter`. + - `"image_generation"` - `"code_interpreter"` - - `allowed_callers: optional array of "direct" or "programmatic"` + - `ToolChoiceFunction object { name, type }` - The tool invocation context(s). + Use this option to force the model to call a specific function. - - `"direct"` + - `name: string` - - `"programmatic"` + The name of the function to call. - - `ProgrammaticToolCalling object { type }` + - `type: "function"` - - `type: "programmatic_tool_calling"` + For function calling, the type is always `function`. - The type of the tool. Always `programmatic_tool_calling`. + - `"function"` - - `"programmatic_tool_calling"` + - `ToolChoiceMcp object { server_label, type, name }` - - `ImageGeneration object { type, action, background, 9 more }` + Use this option to force the model to call a specific tool on a remote MCP server. - A tool that generates images using the GPT image models. + - `server_label: string` - - `type: "image_generation"` + The label of the MCP server to use. - The type of the image generation tool. Always `image_generation`. + - `type: "mcp"` - - `"image_generation"` + For MCP tools, the type is always `mcp`. - - `action: optional "generate" or "edit" or "auto"` + - `"mcp"` - Whether to generate a new image or edit an existing image. Default: `auto`. + - `name: optional string` - - `"generate"` + The name of the tool to call on the server. - - `"edit"` + - `ToolChoiceCustom object { name, type }` - - `"auto"` + Use this option to force the model to call a specific custom tool. - - `background: optional "transparent" or "opaque" or "auto"` + - `name: string` - Background type for the generated image. One of `transparent`, - `opaque`, or `auto`. Default: `auto`. + The name of the custom tool to call. - - `"transparent"` + - `type: "custom"` - - `"opaque"` + For custom tool calling, the type is always `custom`. - - `"auto"` + - `"custom"` - - `input_fidelity: optional "high" or "low"` + - `SpecificProgrammaticToolCallingParam object { type }` - 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: "programmatic_tool_calling"` - - `"high"` + The tool to call. Always `programmatic_tool_calling`. - - `"low"` + - `"programmatic_tool_calling"` - - `input_image_mask: optional object { file_id, image_url }` + - `ToolChoiceApplyPatch object { type }` - Optional mask for inpainting. Contains `image_url` - (string, optional) and `file_id` (string, optional). + Forces the model to call the apply_patch tool when executing a tool call. - - `file_id: optional string` + - `type: "apply_patch"` - File ID for the mask image. + The tool to call. Always `apply_patch`. - - `image_url: optional string` + - `"apply_patch"` - Base64-encoded mask image. + - `ToolChoiceShell object { type }` - - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` + Forces the model to call the shell tool when a tool call is required. - The image generation model to use. Default: `gpt-image-1`. + - `type: "shell"` - - `string` + The tool to call. Always `shell`. - - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` + - `"shell"` - The image generation model to use. Default: `gpt-image-1`. + - `tools: array of object { name, parameters, strict, 5 more } or object { type, vector_store_ids, filters, 2 more } or object { type } or 13 more` - - `"gpt-image-1"` + An array of tools the model may call while generating a response. You + can specify which tool to use by setting the `tool_choice` parameter. - - `"gpt-image-1-mini"` + We support the following categories of tools: - - `"gpt-image-1.5"` + - **Built-in tools**: Tools that are provided by OpenAI that extend the + model's capabilities, like [web search](/docs/guides/tools-web-search) + or [file search](/docs/guides/tools-file-search). Learn more about + [built-in tools](/docs/guides/tools). + - **MCP Tools**: Integrations with third-party systems via custom MCP servers + or predefined connectors such as Google Drive and SharePoint. Learn more about + [MCP Tools](/docs/guides/tools-connectors-mcp). + - **Function calls (custom tools)**: Functions that are defined by you, + enabling the model to call your own code with strongly typed arguments + and outputs. Learn more about + [function calling](/docs/guides/function-calling). You can also use + custom tools to call your own code. - - `moderation: optional "auto" or "low"` + - `Function object { name, parameters, strict, 5 more }` - Moderation level for the generated image. Default: `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` - - `"low"` + The name of the function to call. - - `output_compression: optional number` + - `parameters: map[unknown]` - Compression level for the output image. Default: 100. + A JSON schema object describing the parameters of the function. - - `output_format: optional "png" or "webp" or "jpeg"` + - `strict: boolean` - The output format of the generated image. One of `png`, `webp`, or - `jpeg`. Default: `png`. + Whether strict parameter validation is enforced for this function tool. - - `"png"` + - `type: "function"` - - `"webp"` + The type of the function tool. Always `function`. - - `"jpeg"` + - `"function"` - - `partial_images: optional number` + - `allowed_callers: optional array of "direct" or "programmatic"` - Number of partial images to generate in streaming mode, from 0 (default value) to 3. + The tool invocation context(s). - - `quality: optional "low" or "medium" or "high" or "auto"` + - `"direct"` - The quality of the generated image. One of `low`, `medium`, `high`, - or `auto`. Default: `auto`. + - `"programmatic"` - - `"low"` + - `defer_loading: optional boolean` - - `"medium"` + Whether this function is deferred and loaded via tool search. - - `"high"` + - `description: optional string` - - `"auto"` + A description of the function. Used by the model to determine whether or not to call the function. - - `size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or "auto"` + - `output_schema: optional map[unknown]` - The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. + A JSON schema object describing the JSON value encoded in string outputs for this function. - - `string` + - `FileSearch object { type, vector_store_ids, filters, 2 more }` - - `"1024x1024" or "1024x1536" or "1536x1024" or "auto"` + A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). - 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: "file_search"` - - `"1024x1024"` + The type of the file search tool. Always `file_search`. - - `"1024x1536"` + - `"file_search"` - - `"1536x1024"` + - `vector_store_ids: array of string` - - `"auto"` + The IDs of the vector stores to search. - - `LocalShell object { type }` + - `filters: optional ComparisonFilter or CompoundFilter` - A tool that allows the model to execute shell commands in a local environment. + A filter to apply. - - `type: "local_shell"` + - `ComparisonFilter object { key, type, value }` - The type of the local shell tool. Always `local_shell`. + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - - `"local_shell"` + - `CompoundFilter object { filters, type }` - - `Shell object { type, allowed_callers, environment }` + Combine multiple filters using `and` or `or`. - A tool that allows the model to execute shell commands. + - `max_num_results: optional number` - - `type: "shell"` + The maximum number of results to return. This number should be between 1 and 50 inclusive. - The type of the shell tool. Always `shell`. + - `ranking_options: optional object { hybrid_search, ranker, score_threshold }` - - `"shell"` + Ranking options for search. - - `allowed_callers: optional array of "direct" or "programmatic"` + - `hybrid_search: optional object { embedding_weight, text_weight }` - The tool invocation context(s). + Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. - - `"direct"` + - `embedding_weight: number` - - `"programmatic"` + The weight of the embedding in the reciprocal ranking fusion. - - `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, allowed_callers, 3 more }` - - A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) - - - `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"` - - - `allowed_callers: optional array of "direct" or "programmatic"` - - The tool invocation context(s). - - - `"direct"` - - - `"programmatic"` - - - `defer_loading: optional boolean` - - Whether this tool should be deferred and discovered via tool search. - - - `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, allowed_callers, 5 more } or object { name, type, allowed_callers, 3 more }` - - The function/custom tools available inside this namespace. - - - `Function object { name, type, allowed_callers, 5 more }` - - - `name: string` - - - `type: "function"` - - - `"function"` - - - `allowed_callers: optional array of "direct" or "programmatic"` - - The tool invocation context(s). - - - `"direct"` - - - `"programmatic"` - - - `defer_loading: optional boolean` - - Whether this function should be deferred and discovered via tool search. - - - `description: optional string` - - - `output_schema: optional map[unknown]` - - A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. - - - `parameters: optional unknown` - - - `strict: optional boolean` - - Whether to enforce strict parameter validation. If omitted, Responses attempts to use strict validation when the schema is compatible, and falls back to non-strict validation otherwise. - - - `Custom object { name, type, allowed_callers, 3 more }` - - A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) - - - `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"` - - - `allowed_callers: optional array of "direct" or "programmatic"` - - The tool invocation context(s). - - - `"direct"` - - - `"programmatic"` - - - `defer_loading: optional boolean` - - Whether this tool should be deferred and discovered via tool search. - - - `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, allowed_callers }` - - 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"` - - - `allowed_callers: optional array of "direct" or "programmatic"` - - The tool invocation context(s). - - - `"direct"` - - - `"programmatic"` - - - `type: "tool_search_output"` - - The item type. Always `tool_search_output`. - - - `"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, 5 more } or object { type, vector_store_ids, filters, 2 more } or object { type } or 13 more` - - A list of additional tools made available at this item. - - - `Function object { name, parameters, strict, 5 more }` - - Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). - - - `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 strict parameter validation is enforced for this function tool. - - - `type: "function"` - - The type of the function tool. Always `function`. - - - `"function"` - - - `allowed_callers: optional array of "direct" or "programmatic"` - - The tool invocation context(s). - - - `"direct"` - - - `"programmatic"` - - - `defer_loading: optional boolean` - - Whether this function is deferred and loaded via tool search. - - - `description: optional string` - - A description of the function. Used by the model to determine whether or not to call the function. - - - `output_schema: optional map[unknown]` - - A JSON schema object describing the JSON value encoded in string outputs for this function. - - - `FileSearch object { type, vector_store_ids, filters, 2 more }` - - A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). - - - `type: "file_search"` - - The type of the file search tool. Always `file_search`. - - - `"file_search"` - - - `vector_store_ids: array of string` - - The IDs of the vector stores to search. - - - `filters: optional ComparisonFilter or CompoundFilter` - - A filter to apply. - - - `ComparisonFilter object { key, type, value }` - - A filter used to compare a specified attribute key to a given value using a defined comparison operation. - - - `CompoundFilter object { filters, type }` - - Combine multiple filters using `and` or `or`. - - - `max_num_results: optional number` - - The maximum number of results to return. This number should be between 1 and 50 inclusive. - - - `ranking_options: optional object { hybrid_search, ranker, score_threshold }` - - 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` + - `text_weight: number` The weight of the text in the reciprocal ranking fusion. @@ -8936,1183 +8479,1388 @@ as input for the model's response. - `"programmatic"` - - `type: "additional_tools"` + - `top_p: number` - The item type. Always `additional_tools`. + An alternative to sampling with temperature, called nucleus sampling, + where the model considers the results of the tokens with top_p probability + mass. So 0.1 means only the tokens comprising the top 10% probability mass + are considered. - - `"additional_tools"` + We generally recommend altering this or `temperature` but not both. - - `id: optional string` + - `background: optional boolean` - The unique ID of this additional tools item. + Whether to run the model response in the background. + [Learn more](/docs/guides/background). - - `Reasoning object { id, summary, type, 3 more }` + - `completed_at: optional number` - 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). + Unix timestamp (in seconds) of when this Response was completed. + Only present when the status is `completed`. - - `id: string` + - `conversation: optional object { id }` - The unique identifier of the reasoning content. + The conversation that this response belonged to. Input items and output items from this response were automatically added to this conversation. - - `summary: array of SummaryTextContent` + - `id: string` - Reasoning summary content. + The unique ID of the conversation that this response was associated with. - - `text: string` + - `max_output_tokens: optional number` - A summary of the reasoning output from the model so far. + An upper bound for the number of tokens that can be generated for a response, including visible output tokens and [reasoning tokens](/docs/guides/reasoning). - - `type: "summary_text"` + - `max_tool_calls: optional number` - The type of the object. Always `summary_text`. + The maximum number of total calls to built-in tools that can be processed in a response. This maximum number applies across all built-in tool calls, not per individual tool. Any further attempts to call a tool by the model will be ignored. - - `"summary_text"` + - `moderation: optional object { input, output }` - - `type: "reasoning"` + Moderation results for the response input and output, if moderated completions were requested. - The type of the object. Always `reasoning`. + - `input: object { categories, category_applied_input_types, category_scores, 3 more } or object { code, message, type }` - - `"reasoning"` + Moderation for the response input. - - `content: optional array of object { text, type }` + - `ModerationResult object { categories, category_applied_input_types, category_scores, 3 more }` - Reasoning text content. + A moderation result produced for the response input or output. - - `text: string` + - `categories: map[boolean]` - The reasoning text from the model. + A dictionary of moderation categories to booleans, True if the input is flagged under this category. - - `type: "reasoning_text"` + - `category_applied_input_types: map[array of "text" or "image"]` - The type of the reasoning text. Always `reasoning_text`. + Which modalities of input are reflected by the score for each category. - - `"reasoning_text"` + - `"text"` - - `encrypted_content: optional string` + - `"image"` - The encrypted content of the reasoning item. This is populated by default - for reasoning items returned by `POST /v1/responses` and WebSocket - `response.create` requests. + - `category_scores: map[number]` - - `status: optional "in_progress" or "completed" or "incomplete"` + A dictionary of moderation categories to scores. - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `flagged: boolean` - - `"in_progress"` + A boolean indicating whether the content was flagged by any category. - - `"completed"` + - `model: string` - - `"incomplete"` + The moderation model that produced this result. - - `Compaction object { encrypted_content, type, id }` + - `type: "moderation_result"` - A compaction item generated by the [`v1/responses/compact` API](/docs/api-reference/responses/compact). + The object type, which was always `moderation_result` for successful moderation results. - - `encrypted_content: string` + - `"moderation_result"` - The encrypted content of the compaction summary. + - `Error object { code, message, type }` - - `type: "compaction"` + An error produced while attempting moderation for the response input or output. - The type of the item. Always `compaction`. + - `code: string` - - `"compaction"` + The error code. - - `id: optional string` + - `message: string` - The ID of the compaction item. + The error message. - - `ImageGenerationCall object { id, result, status, type }` + - `type: "error"` - An image generation request made by the model. + The object type, which was always `error` for moderation failures. - - `id: string` + - `"error"` - The unique ID of the image generation call. + - `output: object { categories, category_applied_input_types, category_scores, 3 more } or object { code, message, type }` - - `result: string` + Moderation for the response output. - The generated image encoded in base64. + - `ModerationResult object { categories, category_applied_input_types, category_scores, 3 more }` - - `status: "in_progress" or "completed" or "generating" or "failed"` + A moderation result produced for the response input or output. - The status of the image generation call. + - `categories: map[boolean]` - - `"in_progress"` + A dictionary of moderation categories to booleans, True if the input is flagged under this category. - - `"completed"` + - `category_applied_input_types: map[array of "text" or "image"]` - - `"generating"` + Which modalities of input are reflected by the score for each category. - - `"failed"` + - `"text"` - - `type: "image_generation_call"` + - `"image"` - The type of the image generation call. Always `image_generation_call`. + - `category_scores: map[number]` - - `"image_generation_call"` + A dictionary of moderation categories to scores. - - `CodeInterpreterCall object { id, code, container_id, 3 more }` + - `flagged: boolean` - A tool call to run code. + A boolean indicating whether the content was flagged by any category. - - `id: string` + - `model: string` - The unique ID of the code interpreter tool call. + The moderation model that produced this result. - - `code: string` + - `type: "moderation_result"` - The code to run, or null if not available. + The object type, which was always `moderation_result` for successful moderation results. - - `container_id: string` + - `"moderation_result"` - The ID of the container used to run the code. + - `Error object { code, message, type }` - - `outputs: array of object { logs, type } or object { type, url }` + An error produced while attempting moderation for the response input or output. - The outputs generated by the code interpreter, such as logs or images. - Can be null if no outputs are available. + - `code: string` - - `Logs object { logs, type }` + The error code. - The logs output from the code interpreter. + - `message: string` - - `logs: string` + The error message. - The logs output from the code interpreter. + - `type: "error"` - - `type: "logs"` + The object type, which was always `error` for moderation failures. - The type of the output. Always `logs`. + - `"error"` - - `"logs"` + - `output_text: optional string` - - `Image object { type, url }` + SDK-only convenience property that contains the aggregated text output + from all `output_text` items in the `output` array, if any are present. + Supported in the Python and JavaScript SDKs. - The image output from the code interpreter. + - `previous_response_id: optional string` - - `type: "image"` + The unique ID of the previous response to the model. Use this to + create multi-turn conversations. Learn more about + [conversation state](/docs/guides/conversation-state). Cannot be used in conjunction with `conversation`. - The type of the output. Always `image`. + - `prompt: optional ResponsePrompt` - - `"image"` + Reference to a prompt template and its variables. + [Learn more](/docs/guides/text?api-mode=responses#reusable-prompts). - - `url: string` + - `id: string` - The URL of the image output from the code interpreter. + The unique identifier of the prompt template to use. - - `status: "in_progress" or "completed" or "incomplete" or 2 more` + - `variables: optional map[string or ResponseInputText or ResponseInputImage or ResponseInputFile]` - The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. + Optional map of values to substitute in for variables in your + prompt. The substitution values can either be strings, or other + Response input types like images or files. - - `"in_progress"` + - `string` - - `"completed"` + - `ResponseInputText object { text, type, prompt_cache_breakpoint }` - - `"incomplete"` + A text input to the model. - - `"interpreting"` + - `ResponseInputImage object { detail, type, file_id, 2 more }` - - `"failed"` + An image input to the model. Learn about [image inputs](/docs/guides/vision). - - `type: "code_interpreter_call"` + - `ResponseInputFile object { type, detail, file_data, 4 more }` - The type of the code interpreter tool call. Always `code_interpreter_call`. + A file input to the model. - - `"code_interpreter_call"` + - `version: optional string` - - `LocalShellCall object { id, action, call_id, 2 more }` + Optional version of the prompt template. - A tool call to run a command on the local shell. + - `prompt_cache_key: optional string` - - `id: string` + Used by OpenAI to cache responses for similar requests to optimize your cache hit rates. Replaces the `user` field. [Learn more](/docs/guides/prompt-caching). - The unique ID of the local shell call. + - `prompt_cache_options: optional object { mode, ttl }` - - `action: object { command, env, type, 3 more }` + The prompt-caching options that were applied to the response. Supported for `gpt-5.6` and later models. - Execute a shell command on the server. + - `mode: "implicit" or "explicit"` - - `command: array of string` + Whether implicit prompt-cache breakpoints were enabled. - The command to run. + - `"implicit"` - - `env: map[string]` + - `"explicit"` - Environment variables to set for the command. + - `ttl: "30m"` - - `type: "exec"` + The minimum lifetime applied to each cache breakpoint. - The type of the local shell action. Always `exec`. + - `"30m"` - - `"exec"` + - `prompt_cache_retention: optional "in_memory" or "24h"` - - `timeout_ms: optional number` + Deprecated. Use `prompt_cache_options.ttl` instead. - Optional timeout in milliseconds for the command. + The retention policy for the prompt cache. Set to `24h` to enable extended prompt caching, which keeps cached prefixes active for longer, up to a maximum of 24 hours. [Learn more](/docs/guides/prompt-caching#prompt-cache-retention). + This field expresses a maximum retention policy, while + `prompt_cache_options.ttl` expresses a minimum cache lifetime. The two + fields are independent and do not interact. + For `gpt-5.5`, `gpt-5.5-pro`, and future models, only `24h` is supported. - - `user: optional string` + For older models that support both `in_memory` and `24h`, the default depends on your organization's data retention policy: - Optional user to run the command as. + - Organizations without ZDR enabled default to `24h`. + - Organizations with ZDR enabled default to `in_memory` when `prompt_cache_retention` is not specified. - - `working_directory: optional string` + - `"in_memory"` - Optional working directory to run the command in. + - `"24h"` - - `call_id: string` + - `reasoning: optional Reasoning` - The unique ID of the local shell tool call generated by the model. + **gpt-5 and o-series models only** - - `status: "in_progress" or "completed" or "incomplete"` + Configuration options for + [reasoning models](https://platform.openai.com/docs/guides/reasoning). - The status of the local shell call. + - `context: optional "auto" or "current_turn" or "all_turns"` - - `"in_progress"` + Controls which reasoning items are rendered back to the model on later turns. + If omitted or set to `auto`, the model determines the context mode. The + `gpt-5.6` model family defaults to `all_turns`; earlier models default to + `current_turn`. - - `"completed"` + When returned on a response, this is the effective reasoning context mode + used for the response. - - `"incomplete"` + - `"auto"` - - `type: "local_shell_call"` + - `"current_turn"` - The type of the local shell call. Always `local_shell_call`. + - `"all_turns"` - - `"local_shell_call"` + - `effort: optional ReasoningEffort` - - `LocalShellCallOutput object { id, output, type, status }` + Constrains effort on reasoning for reasoning models. Currently supported + values are `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max`. + Reducing reasoning effort can result in faster responses and fewer tokens + used on reasoning in a response. Not all reasoning models support every + value. See the + [reasoning guide](https://platform.openai.com/docs/guides/reasoning) + for model-specific support. - The output of a local shell tool call. + - `"none"` - - `id: string` + - `"minimal"` - The unique ID of the local shell tool call generated by the model. + - `"low"` - - `output: string` + - `"medium"` - A JSON string of the output of the local shell tool call. + - `"high"` - - `type: "local_shell_call_output"` + - `"xhigh"` - The type of the local shell tool call output. Always `local_shell_call_output`. + - `"max"` - - `"local_shell_call_output"` + - `generate_summary: optional "auto" or "concise" or "detailed"` - - `status: optional "in_progress" or "completed" or "incomplete"` + **Deprecated:** use `summary` instead. - The status of the item. One of `in_progress`, `completed`, or `incomplete`. + A summary of the reasoning performed by the model. This can be + useful for debugging and understanding the model's reasoning process. + One of `auto`, `concise`, or `detailed`. - - `"in_progress"` + - `"auto"` - - `"completed"` + - `"concise"` - - `"incomplete"` + - `"detailed"` - - `ShellCall object { action, call_id, type, 4 more }` + - `mode: optional string or "standard" or "pro"` - A tool representing a request to execute one or more shell commands. + Controls the reasoning execution mode for the request. - - `action: object { commands, max_output_length, timeout_ms }` + When returned on a response, this is the effective execution mode. - The shell commands and limits that describe how to run the tool call. + - `string` - - `commands: array of string` + - `"standard" or "pro"` - Ordered shell commands for the execution environment to run. + Controls the reasoning execution mode for the request. - - `max_output_length: optional number` + When returned on a response, this is the effective execution mode. - Maximum number of UTF-8 characters to capture from combined stdout and stderr output. + - `"standard"` - - `timeout_ms: optional number` + - `"pro"` - Maximum wall-clock time in milliseconds to allow the shell commands to run. + - `summary: optional "auto" or "concise" or "detailed"` - - `call_id: string` + A summary of the reasoning performed by the model. This can be + useful for debugging and understanding the model's reasoning process. + One of `auto`, `concise`, or `detailed`. - The unique ID of the shell tool call generated by the model. + `concise` is supported for `computer-use-preview` models and all reasoning models after `gpt-5`. - - `type: "shell_call"` + - `"auto"` - The type of the item. Always `shell_call`. + - `"concise"` - - `"shell_call"` + - `"detailed"` - - `id: optional string` + - `safety_identifier: optional string` - The unique ID of the shell tool call. Populated when this item is returned via API. + A stable identifier used to help detect users of your application that may be violating OpenAI's usage policies. + The IDs should be a string that uniquely identifies each user, with a maximum length of 64 characters. We recommend hashing their username or email address, in order to avoid sending us any identifying information. [Learn more](/docs/guides/safety-best-practices#safety-identifiers). - - `caller: optional object { type } or object { caller_id, type }` + - `service_tier: optional "auto" or "default" or "flex" or 2 more` - The execution context that produced this tool call. + Specifies the processing type used for serving the request. - - `Direct object { type }` + - If set to 'auto', then the request will be processed with the service tier configured in the Project settings. Unless otherwise configured, the Project will use 'default'. + - If set to 'default', then the request will be processed with the standard pricing and performance for the selected model. + - If set to '[flex](/docs/guides/flex-processing)' or '[priority](https://openai.com/api-priority-processing/)', then the request will be processed with the corresponding service tier. + - When not set, the default behavior is 'auto'. - - `type: "direct"` + When the `service_tier` parameter is set, the response body will include the `service_tier` value based on the processing mode actually used to serve the request. This response value may be different from the value set in the parameter. - The caller type. Always `direct`. + - `"auto"` - - `"direct"` + - `"default"` - - `Program object { caller_id, type }` + - `"flex"` - - `caller_id: string` + - `"scale"` - The call ID of the program item that produced this tool call. + - `"priority"` - - `type: "program"` + - `status: optional ResponseStatus` - The caller type. Always `program`. + The status of the response generation. One of `completed`, `failed`, + `in_progress`, `cancelled`, `queued`, or `incomplete`. - - `"program"` + - `"completed"` - - `environment: optional LocalEnvironment or ContainerReference` + - `"failed"` - The environment to execute the shell commands in. + - `"in_progress"` - - `LocalEnvironment object { type, skills }` + - `"cancelled"` - - `ContainerReference object { container_id, type }` + - `"queued"` - - `status: optional "in_progress" or "completed" or "incomplete"` + - `"incomplete"` - The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. + - `text: optional ResponseTextConfig` - - `"in_progress"` + Configuration options for a text response from the model. Can be plain + text or structured JSON data. Learn more: - - `"completed"` + - [Text inputs and outputs](/docs/guides/text) + - [Structured Outputs](/docs/guides/structured-outputs) - - `"incomplete"` + - `format: optional ResponseFormatTextConfig` - - `ShellCallOutput object { call_id, output, type, 4 more }` + An object specifying the format that the model must output. - The streamed output items emitted by a shell tool call. + Configuring `{ "type": "json_schema" }` enables Structured Outputs, + which ensures the model will match your supplied JSON schema. Learn more in the + [Structured Outputs guide](/docs/guides/structured-outputs). - - `call_id: string` + The default format is `{ "type": "text" }` with no additional options. - The unique ID of the shell tool call generated by the model. + **Not recommended for gpt-4o and newer models:** - - `output: array of ResponseFunctionShellCallOutputContent` + Setting to `{ "type": "json_object" }` enables the older JSON mode, which + ensures the message the model generates is valid JSON. Using `json_schema` + is preferred for models that support it. - Captured chunks of stdout and stderr output, along with their associated outcomes. + - `ResponseFormatText object { type }` - - `outcome: object { type } or object { exit_code, type }` + Default response format. Used to generate text responses. - The exit or timeout outcome associated with this shell call. + - `type: "text"` - - `Timeout object { type }` + The type of response format being defined. Always `text`. - Indicates that the shell call exceeded its configured time limit. + - `"text"` - - `type: "timeout"` + - `ResponseFormatTextJSONSchemaConfig object { name, schema, type, 2 more }` - The outcome type. Always `timeout`. + JSON Schema response format. Used to generate structured JSON responses. + Learn more about [Structured Outputs](/docs/guides/structured-outputs). - - `"timeout"` + - `name: string` - - `Exit object { exit_code, type }` + The name of the response format. Must be a-z, A-Z, 0-9, or contain + underscores and dashes, with a maximum length of 64. - Indicates that the shell commands finished and returned an exit code. + - `schema: map[unknown]` - - `exit_code: number` + The schema for the response format, described as a JSON Schema object. + Learn how to build JSON schemas [here](https://json-schema.org/). - The exit code returned by the shell process. + - `type: "json_schema"` - - `type: "exit"` + The type of response format being defined. Always `json_schema`. - The outcome type. Always `exit`. + - `"json_schema"` - - `"exit"` + - `description: optional string` - - `stderr: string` + A description of what the response format is for, used by the model to + determine how to respond in the format. - Captured stderr output for the shell call. + - `strict: optional boolean` - - `stdout: string` + Whether to enable strict schema adherence when generating the output. + If set to true, the model will always follow the exact schema defined + in the `schema` field. Only a subset of JSON Schema is supported when + `strict` is `true`. To learn more, read the [Structured Outputs + guide](/docs/guides/structured-outputs). - Captured stdout output for the shell call. + - `ResponseFormatJSONObject object { type }` - - `type: "shell_call_output"` + JSON object response format. An older method of generating JSON responses. + Using `json_schema` is recommended for models that support it. Note that the + model will not generate JSON without a system or user message instructing it + to do so. - The type of the item. Always `shell_call_output`. + - `type: "json_object"` - - `"shell_call_output"` + The type of response format being defined. Always `json_object`. - - `id: optional string` + - `"json_object"` - The unique ID of the shell tool call output. Populated when this item is returned via API. + - `verbosity: optional "low" or "medium" or "high"` - - `caller: optional object { type } or object { caller_id, type }` + Constrains the verbosity of the model's response. Lower values will result in + more concise responses, while higher values will result in more verbose responses. + Currently supported values are `low`, `medium`, and `high`. The default is + `medium`. - The execution context that produced this tool call. + - `"low"` - - `Direct object { type }` + - `"medium"` - - `type: "direct"` + - `"high"` - The caller type. Always `direct`. + - `top_logprobs: optional number` - - `"direct"` + An integer between 0 and 20 specifying the maximum number of most likely + tokens to return at each token position, each with an associated log + probability. In some cases, the number of returned tokens may be fewer than + requested. - - `Program object { caller_id, type }` + - `truncation: optional "auto" or "disabled"` - - `caller_id: string` + The truncation strategy to use for the model response. - The call ID of the program item that produced this tool call. + - `auto`: If the input to this Response exceeds + the model's context window size, the model will truncate the + response to fit the context window by dropping items from the beginning of the conversation. + - `disabled` (default): If the input size will exceed the context window + size for a model, the request will fail with a 400 error. - - `type: "program"` + - `"auto"` - The caller type. Always `program`. + - `"disabled"` - - `"program"` + - `usage: optional ResponseUsage` - - `max_output_length: optional number` + Represents token usage details including input tokens, output tokens, + a breakdown of output tokens, and the total tokens used. - The maximum number of UTF-8 characters captured for this shell call's combined output. + - `input_tokens: number` - - `status: optional "in_progress" or "completed" or "incomplete"` + The number of input tokens. - The status of the shell call output. + - `input_tokens_details: object { cache_write_tokens, cached_tokens }` - - `"in_progress"` + A detailed breakdown of the input tokens. - - `"completed"` + - `cache_write_tokens: number` - - `"incomplete"` + The number of input tokens that were written to the cache. - - `ApplyPatchCall object { call_id, operation, status, 3 more }` + - `cached_tokens: number` - A tool call representing a request to create, delete, or update files using diff patches. + The number of tokens that were retrieved from the cache. + [More on prompt caching](/docs/guides/prompt-caching). - - `call_id: string` + - `output_tokens: number` - The unique ID of the apply patch tool call generated by the model. + The number of output tokens. - - `operation: object { diff, path, type } or object { path, type } or object { diff, path, type }` + - `output_tokens_details: object { reasoning_tokens }` - The specific create, delete, or update instruction for the apply_patch tool call. + A detailed breakdown of the output tokens. - - `CreateFile object { diff, path, type }` + - `reasoning_tokens: number` - Instruction for creating a new file via the apply_patch tool. + The number of reasoning tokens. - - `diff: string` + - `total_tokens: number` - Unified diff content to apply when creating the file. + The total number of tokens used. - - `path: string` + - `user: optional string` - Path of the file to create relative to the workspace root. + This field is being replaced by `safety_identifier` and `prompt_cache_key`. Use `prompt_cache_key` instead to maintain caching optimizations. + A stable identifier for your end-users. + Used to boost cache hit rates by better bucketing similar requests and to help OpenAI detect and prevent abuse. [Learn more](/docs/guides/safety-best-practices#safety-identifiers). - - `type: "create_file"` +### Example - The operation type. Always `create_file`. +```http +curl https://api.openai.com/v1/responses/$RESPONSE_ID/cancel \ + -X POST \ + -H "Authorization: Bearer $OPENAI_API_KEY" +``` - - `"create_file"` +#### Response - - `DeleteFile object { path, type }` +```json +{ + "id": "id", + "created_at": 0, + "error": { + "code": "server_error", + "message": "message" + }, + "incomplete_details": { + "reason": "max_output_tokens" + }, + "instructions": "string", + "metadata": { + "foo": "string" + }, + "model": "gpt-5.1", + "object": "response", + "output": [ + { + "id": "id", + "content": [ + { + "annotations": [ + { + "file_id": "file_id", + "filename": "filename", + "index": 0, + "type": "file_citation" + } + ], + "logprobs": [ + { + "token": "token", + "bytes": [ + 0 + ], + "logprob": 0, + "top_logprobs": [ + { + "token": "token", + "bytes": [ + 0 + ], + "logprob": 0 + } + ] + } + ], + "text": "text", + "type": "output_text" + } + ], + "role": "assistant", + "status": "in_progress", + "type": "message", + "phase": "commentary" + } + ], + "parallel_tool_calls": true, + "temperature": 1, + "tool_choice": "none", + "tools": [ + { + "name": "name", + "parameters": { + "foo": "bar" + }, + "strict": true, + "type": "function", + "allowed_callers": [ + "direct" + ], + "defer_loading": true, + "description": "description", + "output_schema": { + "foo": "bar" + } + } + ], + "top_p": 1, + "background": true, + "completed_at": 0, + "conversation": { + "id": "id" + }, + "max_output_tokens": 0, + "max_tool_calls": 0, + "moderation": { + "input": { + "categories": { + "foo": true + }, + "category_applied_input_types": { + "foo": [ + "text" + ] + }, + "category_scores": { + "foo": 0 + }, + "flagged": true, + "model": "model", + "type": "moderation_result" + }, + "output": { + "categories": { + "foo": true + }, + "category_applied_input_types": { + "foo": [ + "text" + ] + }, + "category_scores": { + "foo": 0 + }, + "flagged": true, + "model": "model", + "type": "moderation_result" + } + }, + "output_text": "output_text", + "previous_response_id": "previous_response_id", + "prompt": { + "id": "id", + "variables": { + "foo": "string" + }, + "version": "version" + }, + "prompt_cache_key": "prompt-cache-key-1234", + "prompt_cache_options": { + "mode": "implicit", + "ttl": "30m" + }, + "prompt_cache_retention": "in_memory", + "reasoning": { + "context": "auto", + "effort": "none", + "generate_summary": "auto", + "mode": "standard", + "summary": "auto" + }, + "safety_identifier": "safety-identifier-1234", + "service_tier": "auto", + "status": "completed", + "text": { + "format": { + "type": "text" + }, + "verbosity": "low" + }, + "top_logprobs": 0, + "truncation": "auto", + "usage": { + "input_tokens": 0, + "input_tokens_details": { + "cache_write_tokens": 0, + "cached_tokens": 0 + }, + "output_tokens": 0, + "output_tokens_details": { + "reasoning_tokens": 0 + }, + "total_tokens": 0 + }, + "user": "user-1234" +} +``` - Instruction for deleting an existing file via the apply_patch tool. +### Example - - `path: string` +```http +curl -X POST https://api.openai.com/v1/responses/resp_123/cancel \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $OPENAI_API_KEY" +``` - Path of the file to delete relative to the workspace root. +#### Response - - `type: "delete_file"` +```json +{ + "id": "resp_67cb71b351908190a308f3859487620d06981a8637e6bc44", + "object": "response", + "created_at": 1741386163, + "status": "cancelled", + "background": true, + "completed_at": null, + "error": null, + "incomplete_details": null, + "instructions": null, + "max_output_tokens": null, + "model": "gpt-4o-2024-08-06", + "output": [ + { + "type": "message", + "id": "msg_67cb71b3c2b0819084d481baaaf148f206981a8637e6bc44", + "status": "in_progress", + "role": "assistant", + "content": [ + { + "type": "output_text", + "text": "Silent circuits hum, \nThoughts emerge in data streams— \nDigital dawn breaks.", + "annotations": [] + } + ] + } + ], + "parallel_tool_calls": true, + "previous_response_id": null, + "reasoning": { + "effort": null, + "summary": null + }, + "store": true, + "temperature": 1.0, + "text": { + "format": { + "type": "text" + } + }, + "tool_choice": "auto", + "tools": [], + "top_p": 1.0, + "truncation": "disabled", + "usage": null, + "user": null, + "metadata": {} +} +``` - The operation type. Always `delete_file`. +## Compact a response - - `"delete_file"` +**post** `/responses/compact` - - `UpdateFile object { diff, path, type }` +Compact a conversation. Returns a compacted response object. - Instruction for updating an existing file via the apply_patch tool. +Learn when and how to compact long-running conversations in the [conversation state guide](/docs/guides/conversation-state#managing-the-context-window). For ZDR-compatible compaction details, see [Compaction (advanced)](/docs/guides/conversation-state#compaction-advanced). - - `diff: string` +### Body Parameters - Unified diff content to apply to the existing file. +- `model: "gpt-5.6-sol" or "gpt-5.6-terra" or "gpt-5.6-luna" or 92 more or string` - - `path: string` + Model ID used to generate the response, like `gpt-5` or `o3`. OpenAI offers a wide range of models with different capabilities, performance characteristics, and price points. Refer to the [model guide](/docs/models) to browse and compare available models. - Path of the file to update relative to the workspace root. + - `"gpt-5.6-sol" or "gpt-5.6-terra" or "gpt-5.6-luna" or 92 more` - - `type: "update_file"` + Model ID used to generate the response, like `gpt-5` or `o3`. OpenAI offers a wide range of models with different capabilities, performance characteristics, and price points. Refer to the [model guide](/docs/models) to browse and compare available models. - The operation type. Always `update_file`. + - `"gpt-5.6-sol"` - - `"update_file"` + - `"gpt-5.6-terra"` - - `status: "in_progress" or "completed"` + - `"gpt-5.6-luna"` - The status of the apply patch tool call. One of `in_progress` or `completed`. + - `"gpt-5.4"` - - `"in_progress"` + - `"gpt-5.4-mini"` - - `"completed"` + - `"gpt-5.4-nano"` - - `type: "apply_patch_call"` + - `"gpt-5.4-mini-2026-03-17"` - The type of the item. Always `apply_patch_call`. + - `"gpt-5.4-nano-2026-03-17"` - - `"apply_patch_call"` + - `"gpt-5.3-chat-latest"` - - `id: optional string` + - `"gpt-5.2"` - The unique ID of the apply patch tool call. Populated when this item is returned via API. + - `"gpt-5.2-2025-12-11"` - - `caller: optional object { type } or object { caller_id, type }` + - `"gpt-5.2-chat-latest"` - The execution context that produced this tool call. + - `"gpt-5.2-pro"` - - `Direct object { type }` + - `"gpt-5.2-pro-2025-12-11"` - - `type: "direct"` + - `"gpt-5.1"` - The caller type. Always `direct`. + - `"gpt-5.1-2025-11-13"` - - `"direct"` + - `"gpt-5.1-codex"` - - `Program object { caller_id, type }` + - `"gpt-5.1-mini"` - - `caller_id: string` + - `"gpt-5.1-chat-latest"` - The call ID of the program item that produced this tool call. + - `"gpt-5"` - - `type: "program"` + - `"gpt-5-mini"` - The caller type. Always `program`. + - `"gpt-5-nano"` - - `"program"` + - `"gpt-5-2025-08-07"` - - `ApplyPatchCallOutput object { call_id, status, type, 3 more }` + - `"gpt-5-mini-2025-08-07"` - The streamed output emitted by an apply patch tool call. + - `"gpt-5-nano-2025-08-07"` - - `call_id: string` + - `"gpt-5-chat-latest"` - The unique ID of the apply patch tool call generated by the model. + - `"gpt-4.1"` - - `status: "completed" or "failed"` + - `"gpt-4.1-mini"` - The status of the apply patch tool call output. One of `completed` or `failed`. + - `"gpt-4.1-nano"` - - `"completed"` + - `"gpt-4.1-2025-04-14"` - - `"failed"` + - `"gpt-4.1-mini-2025-04-14"` - - `type: "apply_patch_call_output"` + - `"gpt-4.1-nano-2025-04-14"` - The type of the item. Always `apply_patch_call_output`. + - `"o4-mini"` - - `"apply_patch_call_output"` + - `"o4-mini-2025-04-16"` - - `id: optional string` + - `"o3"` - The unique ID of the apply patch tool call output. Populated when this item is returned via API. + - `"o3-2025-04-16"` - - `caller: optional object { type } or object { caller_id, type }` + - `"o3-mini"` - The execution context that produced this tool call. + - `"o3-mini-2025-01-31"` - - `Direct object { type }` + - `"o1"` - - `type: "direct"` + - `"o1-2024-12-17"` - The caller type. Always `direct`. + - `"o1-preview"` - - `"direct"` + - `"o1-preview-2024-09-12"` - - `Program object { caller_id, type }` + - `"o1-mini"` - - `caller_id: string` + - `"o1-mini-2024-09-12"` - The call ID of the program item that produced this tool call. + - `"gpt-4o"` - - `type: "program"` + - `"gpt-4o-2024-11-20"` - The caller type. Always `program`. + - `"gpt-4o-2024-08-06"` - - `"program"` + - `"gpt-4o-2024-05-13"` - - `output: optional string` + - `"gpt-4o-audio-preview"` - Optional human-readable log text from the apply patch tool (e.g., patch results or errors). + - `"gpt-4o-audio-preview-2024-10-01"` - - `McpListTools object { id, server_label, tools, 2 more }` + - `"gpt-4o-audio-preview-2024-12-17"` - A list of tools available on an MCP server. + - `"gpt-4o-audio-preview-2025-06-03"` - - `id: string` + - `"gpt-4o-mini-audio-preview"` - The unique ID of the list. + - `"gpt-4o-mini-audio-preview-2024-12-17"` - - `server_label: string` + - `"gpt-4o-search-preview"` - The label of the MCP server. + - `"gpt-4o-mini-search-preview"` - - `tools: array of object { input_schema, name, annotations, description }` + - `"gpt-4o-search-preview-2025-03-11"` - The tools available on the server. + - `"gpt-4o-mini-search-preview-2025-03-11"` - - `input_schema: unknown` + - `"chatgpt-4o-latest"` - The JSON schema describing the tool's input. + - `"codex-mini-latest"` - - `name: string` + - `"gpt-4o-mini"` - The name of the tool. + - `"gpt-4o-mini-2024-07-18"` - - `annotations: optional unknown` + - `"gpt-4-turbo"` - Additional annotations about the tool. + - `"gpt-4-turbo-2024-04-09"` - - `description: optional string` + - `"gpt-4-0125-preview"` - The description of the tool. + - `"gpt-4-turbo-preview"` - - `type: "mcp_list_tools"` + - `"gpt-4-1106-preview"` - The type of the item. Always `mcp_list_tools`. + - `"gpt-4-vision-preview"` - - `"mcp_list_tools"` + - `"gpt-4"` - - `error: optional string` + - `"gpt-4-0314"` - Error message if the server could not list tools. + - `"gpt-4-0613"` - - `McpApprovalRequest object { id, arguments, name, 2 more }` + - `"gpt-4-32k"` - A request for human approval of a tool invocation. + - `"gpt-4-32k-0314"` - - `id: string` + - `"gpt-4-32k-0613"` - The unique ID of the approval request. + - `"gpt-3.5-turbo"` - - `arguments: string` + - `"gpt-3.5-turbo-16k"` - A JSON string of arguments for the tool. + - `"gpt-3.5-turbo-0301"` - - `name: string` + - `"gpt-3.5-turbo-0613"` - The name of the tool to run. + - `"gpt-3.5-turbo-1106"` - - `server_label: string` + - `"gpt-3.5-turbo-0125"` - The label of the MCP server making the request. + - `"gpt-3.5-turbo-16k-0613"` - - `type: "mcp_approval_request"` + - `"o1-pro"` - The type of the item. Always `mcp_approval_request`. + - `"o1-pro-2025-03-19"` - - `"mcp_approval_request"` + - `"o3-pro"` - - `McpApprovalResponse object { approval_request_id, approve, type, 2 more }` + - `"o3-pro-2025-06-10"` - A response to an MCP approval request. + - `"o3-deep-research"` - - `approval_request_id: string` + - `"o3-deep-research-2025-06-26"` - The ID of the approval request being answered. + - `"o4-mini-deep-research"` - - `approve: boolean` + - `"o4-mini-deep-research-2025-06-26"` - Whether the request was approved. + - `"computer-use-preview"` - - `type: "mcp_approval_response"` + - `"computer-use-preview-2025-03-11"` - The type of the item. Always `mcp_approval_response`. + - `"gpt-5-codex"` - - `"mcp_approval_response"` + - `"gpt-5-pro"` - - `id: optional string` + - `"gpt-5-pro-2025-10-06"` - The unique ID of the approval response + - `"gpt-5.1-codex-max"` - - `reason: optional string` + - `string` - Optional reason for the decision. +- `input: optional string or array of EasyInputMessage or object { content, role, status, type } or ResponseOutputMessage or 29 more` - - `McpCall object { id, arguments, name, 6 more }` + Text, image, or file inputs to the model, used to generate a response - An invocation of a tool on an MCP server. + - `string` - - `id: string` + A text input to the model, equivalent to a text input with the `user` role. - The unique ID of the tool call. + - `array of EasyInputMessage or object { content, role, status, type } or ResponseOutputMessage or 29 more` - - `arguments: string` + A list of one or many input items to the model, containing different content types. - A JSON string of the arguments passed to the tool. + - `EasyInputMessage object { content, role, phase, type }` - - `name: string` + 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. - The name of the tool that was run. + - `content: string or ResponseInputMessageContentList` - - `server_label: string` + Text, image, or audio input to the model, used to generate a response. + Can also contain previous assistant responses. - The label of the MCP server running the tool. + - `TextInput = string` - - `type: "mcp_call"` + A text input to the model. - The type of the item. Always `mcp_call`. + - `ResponseInputMessageContentList = array of ResponseInputContent` - - `"mcp_call"` + A list of one or many input items to the model, containing different content + types. - - `approval_request_id: optional string` + - `ResponseInputText object { text, type, prompt_cache_breakpoint }` - 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 text input to the model. - - `error: optional string` + - `text: 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, 2 more }` - - 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. + The text input to the model. - - `output: string or array of ResponseInputText or ResponseInputImage or ResponseInputFile` + - `type: "input_text"` - The output from the custom tool call generated by your code. - Can be a string or an list of output content. + The type of the input item. Always `input_text`. - - `StringOutput = string` + - `"input_text"` - A string of the output of the custom tool call. + - `prompt_cache_breakpoint: optional object { mode }` - - `OutputContentList = array of ResponseInputText or ResponseInputImage or ResponseInputFile` + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - Text, image, or file output of the custom tool call. + - `mode: "explicit"` - - `ResponseInputText object { text, type, prompt_cache_breakpoint }` + The breakpoint mode. Always `explicit`. - A text input to the model. + - `"explicit"` - `ResponseInputImage object { detail, type, file_id, 2 more }` An image input to the model. Learn about [image inputs](/docs/guides/vision). - - `ResponseInputFile object { type, detail, file_data, 4 more }` - - A file input to the model. - - - `type: "custom_tool_call_output"` - - The type of the custom tool call output. Always `custom_tool_call_output`. - - - `"custom_tool_call_output"` - - - `id: optional string` - - The unique ID of the custom tool call output in the OpenAI platform. - - - `caller: optional object { type } or object { caller_id, type }` - - The execution context that produced this tool call. - - - `Direct object { type }` - - - `type: "direct"` - - The caller type. Always `direct`. + - `detail: "low" or "high" or "auto" or "original"` - - `"direct"` + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - - `Program object { caller_id, type }` + - `"low"` - - `caller_id: string` + - `"high"` - The call ID of the program item that produced this tool call. + - `"auto"` - - `type: "program"` + - `"original"` - The caller type. Always `program`. + - `type: "input_image"` - - `"program"` + The type of the input item. Always `input_image`. - - `CustomToolCall object { call_id, input, name, 4 more }` + - `"input_image"` - A call to a custom tool created by the model. + - `file_id: optional string` - - `call_id: string` + The ID of the file to be sent to the model. - An identifier used to map this custom tool call to a tool call output. + - `image_url: optional string` - - `input: 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 input for the custom tool call generated by the model. + - `prompt_cache_breakpoint: optional object { mode }` - - `name: string` + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - The name of the custom tool being called. + - `mode: "explicit"` - - `type: "custom_tool_call"` + The breakpoint mode. Always `explicit`. - The type of the custom tool call. Always `custom_tool_call`. + - `"explicit"` - - `"custom_tool_call"` + - `ResponseInputFile object { type, detail, file_data, 4 more }` - - `id: optional string` + A file input to the model. - The unique ID of the custom tool call in the OpenAI platform. + - `type: "input_file"` - - `caller: optional object { type } or object { caller_id, type }` + The type of the input item. Always `input_file`. - The execution context that produced this tool call. + - `"input_file"` - - `Direct object { type }` + - `detail: optional "auto" or "low" or "high"` - - `type: "direct"` + The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. - - `"direct"` + - `"auto"` - - `Program object { caller_id, type }` + - `"low"` - - `caller_id: string` + - `"high"` - The call ID of the program item that produced this tool call. + - `file_data: optional string` - - `type: "program"` + The content of the file to be sent to the model. - - `"program"` + - `file_id: optional string` - - `namespace: optional string` + The ID of the file to be sent to the model. - The namespace of the custom tool being called. + - `file_url: optional string` - - `CompactionTrigger object { type }` + The URL of the file to be sent to the model. - Compacts the current context. Must be the final input item. + - `filename: optional string` - - `type: "compaction_trigger"` + The name of the file to be sent to the model. - The type of the item. Always `compaction_trigger`. + - `prompt_cache_breakpoint: optional object { mode }` - - `"compaction_trigger"` + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - `ItemReference object { id, type }` + - `mode: "explicit"` - An internal identifier for an item to reference. + The breakpoint mode. Always `explicit`. - - `id: string` + - `"explicit"` - The ID of the item to reference. + - `role: "user" or "assistant" or "system" or "developer"` - - `type: optional "item_reference"` + The role of the message input. One of `user`, `assistant`, `system`, or + `developer`. - The type of item to reference. Always `item_reference`. + - `"user"` - - `"item_reference"` + - `"assistant"` - - `Program object { id, call_id, code, 2 more }` + - `"system"` - - `id: string` + - `"developer"` - The unique ID of this program item. + - `phase: optional "commentary" or "final_answer"` - - `call_id: 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 stable call ID of the program item. + - `"commentary"` - - `code: string` + - `"final_answer"` - The JavaScript source executed by programmatic tool calling. + - `type: optional "message"` - - `fingerprint: string` + The type of the message input. Always `message`. - Opaque program replay fingerprint that must be round-tripped. + - `"message"` - - `type: "program"` + - `Message object { content, role, status, type }` - The item type. Always `program`. + 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. - - `"program"` + - `content: ResponseInputMessageContentList` - - `ProgramOutput object { id, call_id, result, 2 more }` + A list of one or many input items to the model, containing different content + types. - - `id: string` + - `role: "user" or "system" or "developer"` - The unique ID of this program output item. + The role of the message input. One of `user`, `system`, or `developer`. - - `call_id: string` + - `"user"` - The call ID of the program item. + - `"system"` - - `result: string` + - `"developer"` - The result produced by the program item. + - `status: optional "in_progress" or "completed" or "incomplete"` - - `status: "completed" or "incomplete"` + The status of item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - The terminal status of the program output. + - `"in_progress"` - `"completed"` - `"incomplete"` - - `type: "program_output"` - - The item type. Always `program_output`. - - - `"program_output"` - - - `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. - - - `model: ResponsesModel` - - Model ID used to generate the response, like `gpt-4o` or `o3`. OpenAI - offers a wide range of models with different capabilities, performance - characteristics, and price points. Refer to the [model guide](/docs/models) - to browse and compare available models. - - - `string` - - - `"gpt-5.6-sol" or "gpt-5.6-terra" or "gpt-5.6-luna" or 78 more` - - - `"gpt-5.6-sol"` - - - `"gpt-5.6-terra"` - - - `"gpt-5.6-luna"` - - - `"gpt-5.4"` - - - `"gpt-5.4-mini"` - - - `"gpt-5.4-nano"` - - - `"gpt-5.4-mini-2026-03-17"` - - - `"gpt-5.4-nano-2026-03-17"` - - - `"gpt-5.3-chat-latest"` + - `type: optional "message"` - - `"gpt-5.2"` + The type of the message input. Always set to `message`. - - `"gpt-5.2-2025-12-11"` + - `"message"` - - `"gpt-5.2-chat-latest"` + - `ResponseOutputMessage object { id, content, role, 3 more }` - - `"gpt-5.2-pro"` + An output message from the model. - - `"gpt-5.2-pro-2025-12-11"` + - `id: string` - - `"gpt-5.1"` + The unique ID of the output message. - - `"gpt-5.1-2025-11-13"` + - `content: array of ResponseOutputText or ResponseOutputRefusal` - - `"gpt-5.1-codex"` + The content of the output message. - - `"gpt-5.1-mini"` + - `ResponseOutputText object { annotations, logprobs, text, type }` - - `"gpt-5.1-chat-latest"` + A text output from the model. - - `"gpt-5"` + - `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 }` - - `"gpt-5-mini"` + The annotations of the text output. - - `"gpt-5-nano"` + - `FileCitation object { file_id, filename, index, type }` - - `"gpt-5-2025-08-07"` + A citation to a file. - - `"gpt-5-mini-2025-08-07"` + - `file_id: string` - - `"gpt-5-nano-2025-08-07"` + The ID of the file. - - `"gpt-5-chat-latest"` + - `filename: string` - - `"gpt-4.1"` + The filename of the file cited. - - `"gpt-4.1-mini"` + - `index: number` - - `"gpt-4.1-nano"` + The index of the file in the list of files. - - `"gpt-4.1-2025-04-14"` + - `type: "file_citation"` - - `"gpt-4.1-mini-2025-04-14"` + The type of the file citation. Always `file_citation`. - - `"gpt-4.1-nano-2025-04-14"` + - `"file_citation"` - - `"o4-mini"` + - `URLCitation object { end_index, start_index, title, 2 more }` - - `"o4-mini-2025-04-16"` + A citation for a web resource used to generate a model response. - - `"o3"` + - `end_index: number` - - `"o3-2025-04-16"` + The index of the last character of the URL citation in the message. - - `"o3-mini"` + - `start_index: number` - - `"o3-mini-2025-01-31"` + The index of the first character of the URL citation in the message. - - `"o1"` + - `title: string` - - `"o1-2024-12-17"` + The title of the web resource. - - `"o1-preview"` + - `type: "url_citation"` - - `"o1-preview-2024-09-12"` + The type of the URL citation. Always `url_citation`. - - `"o1-mini"` + - `"url_citation"` - - `"o1-mini-2024-09-12"` + - `url: string` - - `"gpt-4o"` + The URL of the web resource. - - `"gpt-4o-2024-11-20"` + - `ContainerFileCitation object { container_id, end_index, file_id, 3 more }` - - `"gpt-4o-2024-08-06"` + A citation for a container file used to generate a model response. - - `"gpt-4o-2024-05-13"` + - `container_id: string` - - `"gpt-4o-audio-preview"` + The ID of the container file. - - `"gpt-4o-audio-preview-2024-10-01"` + - `end_index: number` - - `"gpt-4o-audio-preview-2024-12-17"` + The index of the last character of the container file citation in the message. - - `"gpt-4o-audio-preview-2025-06-03"` + - `file_id: string` - - `"gpt-4o-mini-audio-preview"` + The ID of the file. - - `"gpt-4o-mini-audio-preview-2024-12-17"` + - `filename: string` - - `"gpt-4o-search-preview"` + The filename of the container file cited. - - `"gpt-4o-mini-search-preview"` + - `start_index: number` - - `"gpt-4o-search-preview-2025-03-11"` + The index of the first character of the container file citation in the message. - - `"gpt-4o-mini-search-preview-2025-03-11"` + - `type: "container_file_citation"` - - `"chatgpt-4o-latest"` + The type of the container file citation. Always `container_file_citation`. - - `"codex-mini-latest"` + - `"container_file_citation"` - - `"gpt-4o-mini"` + - `FilePath object { file_id, index, type }` - - `"gpt-4o-mini-2024-07-18"` + A path to a file. - - `"gpt-4-turbo"` + - `file_id: string` - - `"gpt-4-turbo-2024-04-09"` + The ID of the file. - - `"gpt-4-0125-preview"` + - `index: number` - - `"gpt-4-turbo-preview"` + The index of the file in the list of files. - - `"gpt-4-1106-preview"` + - `type: "file_path"` - - `"gpt-4-vision-preview"` + The type of the file path. Always `file_path`. - - `"gpt-4"` + - `"file_path"` - - `"gpt-4-0314"` + - `logprobs: array of object { token, bytes, logprob, top_logprobs }` - - `"gpt-4-0613"` + - `token: string` - - `"gpt-4-32k"` + - `bytes: array of number` - - `"gpt-4-32k-0314"` + - `logprob: number` - - `"gpt-4-32k-0613"` + - `top_logprobs: array of object { token, bytes, logprob }` - - `"gpt-3.5-turbo"` + - `token: string` - - `"gpt-3.5-turbo-16k"` + - `bytes: array of number` - - `"gpt-3.5-turbo-0301"` + - `logprob: number` - - `"gpt-3.5-turbo-0613"` + - `text: string` - - `"gpt-3.5-turbo-1106"` + The text output from the model. - - `"gpt-3.5-turbo-0125"` + - `type: "output_text"` - - `"gpt-3.5-turbo-16k-0613"` + The type of the output text. Always `output_text`. - - `ResponsesOnlyModel = "o1-pro" or "o1-pro-2025-03-19" or "o3-pro" or 11 more` + - `"output_text"` - - `"o1-pro"` + - `ResponseOutputRefusal object { refusal, type }` - - `"o1-pro-2025-03-19"` + A refusal from the model. - - `"o3-pro"` + - `refusal: string` - - `"o3-pro-2025-06-10"` + The refusal explanation from the model. - - `"o3-deep-research"` + - `type: "refusal"` - - `"o3-deep-research-2025-06-26"` + The type of the refusal. Always `refusal`. - - `"o4-mini-deep-research"` + - `"refusal"` - - `"o4-mini-deep-research-2025-06-26"` + - `role: "assistant"` - - `"computer-use-preview"` + The role of the output message. Always `assistant`. - - `"computer-use-preview-2025-03-11"` + - `"assistant"` - - `"gpt-5-codex"` + - `status: "in_progress" or "completed" or "incomplete"` - - `"gpt-5-pro"` + The status of the message input. One of `in_progress`, `completed`, or + `incomplete`. Populated when input items are returned via API. - - `"gpt-5-pro-2025-10-06"` + - `"in_progress"` - - `"gpt-5.1-codex-max"` + - `"completed"` - - `object: "response"` + - `"incomplete"` - The object type of this resource - always set to `response`. + - `type: "message"` - - `"response"` + The type of the output message. Always `message`. - - `output: array of ResponseOutputItem` + - `"message"` - An array of content items generated by the model. + - `phase: optional "commentary" or "final_answer"` - - The length and order of items in the `output` array is dependent - on the model's response. - - Rather than accessing the first item in the `output` array and - assuming it's an `assistant` message with the content generated by - the model, you might consider using the `output_text` property where - supported in SDKs. + 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. - - `ResponseOutputMessage object { id, content, role, 3 more }` + - `"commentary"` - An output message from the model. + - `"final_answer"` - `FileSearchCall object { id, queries, status, 2 more }` @@ -10182,304 +9930,291 @@ as input for the model's response. The text that was retrieved from the file. - - `FunctionCall object { arguments, call_id, name, 5 more }` + - `ComputerCall object { id, call_id, pending_safety_checks, 4 more }` - A tool call to run a function. See the - [function calling guide](/docs/guides/function-calling) for more information. + A tool call to a computer use tool. See the + [computer use guide](/docs/guides/tools-computer-use) for more information. - - `arguments: string` + - `id: string` - A JSON string of the arguments to pass to the function. + The unique ID of the computer call. - `call_id: string` - The unique ID of the function tool call generated by the model. + An identifier used when responding to the tool call with output. - - `name: string` + - `pending_safety_checks: array of object { id, code, message }` - The name of the function to run. + The pending safety checks for the computer call. - - `type: "function_call"` + - `id: string` - The type of the function tool call. Always `function_call`. + The ID of the pending safety check. - - `"function_call"` + - `code: optional string` - - `id: optional string` + The type of the pending safety check. - The unique ID of the function tool call. + - `message: optional string` - - `caller: optional object { type } or object { caller_id, type }` + Details about the pending safety check. - The execution context that produced this tool call. + - `status: "in_progress" or "completed" or "incomplete"` - - `Direct object { type }` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `type: "direct"` + - `"in_progress"` - - `"direct"` + - `"completed"` - - `Program object { caller_id, type }` + - `"incomplete"` - - `caller_id: string` + - `type: "computer_call"` - The call ID of the program item that produced this tool call. + The type of the computer call. Always `computer_call`. - - `type: "program"` + - `"computer_call"` - - `"program"` + - `action: optional ComputerAction` - - `namespace: optional string` + A click action. - The namespace of the function to run. + - `Click object { button, type, x, 2 more }` - - `status: optional "in_progress" or "completed" or "incomplete"` + A click action. - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `button: "left" or "right" or "wheel" or 2 more` - - `"in_progress"` + Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. - - `"completed"` + - `"left"` - - `"incomplete"` + - `"right"` - - `FunctionCallOutput object { id, call_id, output, 4 more }` + - `"wheel"` - - `id: string` - - The unique ID of the function call tool output. - - - `call_id: string` - - The unique ID of the function tool call generated by the model. - - - `output: string or array of ResponseInputText or ResponseInputImage or ResponseInputFile` - - The output from the function call generated by your code. - Can be a string or an list of output content. - - - `StringOutput = string` + - `"back"` - A string of the output of the function call. + - `"forward"` - - `OutputContentList = array of ResponseInputText or ResponseInputImage or ResponseInputFile` + - `type: "click"` - Text, image, or file output of the function call. + Specifies the event type. For a click action, this property is always `click`. - - `ResponseInputText object { text, type, prompt_cache_breakpoint }` + - `"click"` - A text input to the model. + - `x: number` - - `ResponseInputImage object { detail, type, file_id, 2 more }` + The x-coordinate where the click occurred. - An image input to the model. Learn about [image inputs](/docs/guides/vision). + - `y: number` - - `ResponseInputFile object { type, detail, file_data, 4 more }` + The y-coordinate where the click occurred. - A file input to the model. + - `keys: optional array of string` - - `status: "in_progress" or "completed" or "incomplete"` + The keys being held while clicking. - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `DoubleClick object { keys, type, x, y }` - - `"in_progress"` + A double click action. - - `"completed"` + - `keys: array of string` - - `"incomplete"` + The keys being held while double-clicking. - - `type: "function_call_output"` + - `type: "double_click"` - The type of the function tool call output. Always `function_call_output`. + Specifies the event type. For a double click action, this property is always set to `double_click`. - - `"function_call_output"` + - `"double_click"` - - `caller: optional object { type } or object { caller_id, type }` + - `x: number` - The execution context that produced this tool call. + The x-coordinate where the double click occurred. - - `Direct object { type }` + - `y: number` - - `type: "direct"` + The y-coordinate where the double click occurred. - The caller type. Always `direct`. + - `Drag object { path, type, keys }` - - `"direct"` + A drag action. - - `Program object { caller_id, type }` + - `path: array of object { x, y }` - - `caller_id: string` + An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg - The call ID of the program item that produced this tool call. + ``` + [ + { x: 100, y: 200 }, + { x: 200, y: 300 } + ] + ``` - - `type: "program"` + - `x: number` - The caller type. Always `program`. + The x-coordinate. - - `"program"` + - `y: number` - - `created_by: optional string` + The y-coordinate. - The identifier of the actor that created the item. + - `type: "drag"` - - `WebSearchCall object { id, action, status, type }` + Specifies the event type. For a drag action, this property is always set to `drag`. - The results of a web search tool call. See the - [web search guide](/docs/guides/tools-web-search) for more information. + - `"drag"` - - `id: string` + - `keys: optional array of string` - The unique ID of the web search tool call. + The keys being held while dragging the mouse. - - `action: object { type, queries, query, sources } or object { type, url } or object { pattern, type, url }` + - `Keypress object { keys, 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). + A collection of keypresses the model would like to perform. - - `Search object { type, queries, query, sources }` + - `keys: array of string` - Action type "search" - Performs a web search query. + The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. - - `type: "search"` + - `type: "keypress"` - The action type. + Specifies the event type. For a keypress action, this property is always set to `keypress`. - - `"search"` + - `"keypress"` - - `queries: optional array of string` + - `Move object { type, x, y, keys }` - The search queries. + A mouse move action. - - `query: optional string` + - `type: "move"` - The search query. + Specifies the event type. For a move action, this property is always set to `move`. - - `sources: optional array of object { type, url }` + - `"move"` - The sources used in the search. + - `x: number` - - `type: "url"` + The x-coordinate to move to. - The type of source. Always `url`. + - `y: number` - - `"url"` + The y-coordinate to move to. - - `url: string` + - `keys: optional array of string` - The URL of the source. + The keys being held while moving the mouse. - - `OpenPage object { type, url }` + - `Screenshot object { type }` - Action type "open_page" - Opens a specific URL from search results. + A screenshot action. - - `type: "open_page"` + - `type: "screenshot"` - The action type. + Specifies the event type. For a screenshot action, this property is always set to `screenshot`. - - `"open_page"` + - `"screenshot"` - - `url: optional string` + - `Scroll object { scroll_x, scroll_y, type, 3 more }` - The URL opened by the model. + A scroll action. - - `FindInPage object { pattern, type, url }` + - `scroll_x: number` - Action type "find_in_page": Searches for a pattern within a loaded page. + The horizontal scroll distance. - - `pattern: string` + - `scroll_y: number` - The pattern or text to search for within the page. + The vertical scroll distance. - - `type: "find_in_page"` + - `type: "scroll"` - The action type. + Specifies the event type. For a scroll action, this property is always set to `scroll`. - - `"find_in_page"` + - `"scroll"` - - `url: string` + - `x: number` - The URL of the page searched for the pattern. + The x-coordinate where the scroll occurred. - - `status: "in_progress" or "searching" or "completed" or "failed"` + - `y: number` - The status of the web search tool call. + The y-coordinate where the scroll occurred. - - `"in_progress"` + - `keys: optional array of string` - - `"searching"` + The keys being held while scrolling. - - `"completed"` + - `Type object { text, type }` - - `"failed"` + An action to type in text. - - `type: "web_search_call"` + - `text: string` - The type of the web search tool call. Always `web_search_call`. + The text to type. - - `"web_search_call"` + - `type: "type"` - - `ComputerCall object { id, call_id, pending_safety_checks, 4 more }` + Specifies the event type. For a type action, this property is always set to `type`. - A tool call to a computer use tool. See the - [computer use guide](/docs/guides/tools-computer-use) for more information. + - `"type"` - - `id: string` + - `Wait object { type }` - The unique ID of the computer call. + A wait action. - - `call_id: string` + - `type: "wait"` - An identifier used when responding to the tool call with output. + Specifies the event type. For a wait action, this property is always set to `wait`. - - `pending_safety_checks: array of object { id, code, message }` + - `"wait"` - The pending safety checks for the computer call. + - `actions: optional ComputerActionList` - - `id: string` + Flattened batched actions for `computer_use`. Each action includes an + `type` discriminator and action-specific fields. - The ID of the pending safety check. + - `Click object { button, type, x, 2 more }` - - `code: optional string` + A click action. - The type of the pending safety check. + - `DoubleClick object { keys, type, x, y }` - - `message: optional string` + A double click action. - Details about the pending safety check. + - `Drag object { path, type, keys }` - - `status: "in_progress" or "completed" or "incomplete"` + A drag action. - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `Keypress object { keys, type }` - - `"in_progress"` + A collection of keypresses the model would like to perform. - - `"completed"` + - `Move object { type, x, y, keys }` - - `"incomplete"` + A mouse move action. - - `type: "computer_call"` + - `Screenshot object { type }` - The type of the computer call. Always `computer_call`. + A screenshot action. - - `"computer_call"` + - `Scroll object { scroll_x, scroll_y, type, 3 more }` - - `action: optional ComputerAction` + A scroll action. - A click action. + - `Type object { text, type }` - - `actions: optional ComputerActionList` + An action to type in text. - Flattened batched actions for `computer_use`. Each action includes an - `type` discriminator and action-specific fields. + - `Wait object { type }` - - `ComputerCallOutput object { id, call_id, output, 4 more }` + A wait action. - - `id: string` + - `ComputerCallOutput object { call_id, output, type, 3 more }` - The unique ID of the computer call tool output. + The output of a computer tool call. - `call_id: string` @@ -10489,18 +10224,20 @@ as input for the model's response. A computer screenshot image used with the computer use tool. - - `status: "completed" or "incomplete" or "failed" or "in_progress"` + - `type: "computer_screenshot"` - The status of the message input. One of `in_progress`, `completed`, or - `incomplete`. Populated when input items are returned via API. + Specifies the event type. For a computer screenshot, this property is + always set to `computer_screenshot`. - - `"completed"` + - `"computer_screenshot"` - - `"incomplete"` + - `file_id: optional string` - - `"failed"` + The identifier of an uploaded file that contains the screenshot. - - `"in_progress"` + - `image_url: optional string` + + The URL of the screenshot image. - `type: "computer_call_output"` @@ -10508,10 +10245,13 @@ as input for the model's response. - `"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. + The safety checks reported by the API that have been acknowledged by the developer. - `id: string` @@ -10525,185 +10265,167 @@ as input for the model's response. Details about the pending safety check. - - `created_by: optional string` - - The identifier of the actor that created the 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). + - `status: optional "in_progress" or "completed" or "incomplete"` - - `id: string` + The status of the message input. One of `in_progress`, `completed`, or `incomplete`. Populated when input items are returned via API. - The unique identifier of the reasoning content. + - `"in_progress"` - - `summary: array of SummaryTextContent` + - `"completed"` - Reasoning summary content. + - `"incomplete"` - - `text: string` + - `WebSearchCall object { id, action, status, type }` - A summary of the reasoning output from the model so far. + The results of a web search tool call. See the + [web search guide](/docs/guides/tools-web-search) for more information. - - `type: "summary_text"` + - `id: string` - The type of the object. Always `summary_text`. + The unique ID of the web search tool call. - - `type: "reasoning"` + - `action: object { type, queries, query, sources } or object { type, url } or object { pattern, type, url }` - The type of the object. Always `reasoning`. + 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). - - `"reasoning"` + - `Search object { type, queries, query, sources }` - - `content: optional array of object { text, type }` + Action type "search" - Performs a web search query. - Reasoning text content. + - `type: "search"` - - `text: string` + The action type. - The reasoning text from the model. + - `"search"` - - `type: "reasoning_text"` + - `queries: optional array of string` - The type of the reasoning text. Always `reasoning_text`. + The search queries. - - `"reasoning_text"` + - `query: optional string` - - `encrypted_content: optional string` + The search query. - The encrypted content of the reasoning item. This is populated by default - for reasoning items returned by `POST /v1/responses` and WebSocket - `response.create` requests. + - `sources: optional array of object { type, url }` - - `status: optional "in_progress" or "completed" or "incomplete"` + The sources used in the search. - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `type: "url"` - - `"in_progress"` + The type of source. Always `url`. - - `"completed"` + - `"url"` - - `"incomplete"` + - `url: string` - - `Program object { id, call_id, code, 2 more }` + The URL of the source. - - `id: string` + - `OpenPage object { type, url }` - The unique ID of the program item. + Action type "open_page" - Opens a specific URL from search results. - - `call_id: string` + - `type: "open_page"` - The stable call ID of the program item. + The action type. - - `code: string` + - `"open_page"` - The JavaScript source executed by programmatic tool calling. + - `url: optional string` - - `fingerprint: string` + The URL opened by the model. - Opaque program replay fingerprint that must be round-tripped. + - `FindInPage object { pattern, type, url }` - - `type: "program"` + Action type "find_in_page": Searches for a pattern within a loaded page. - The type of the item. Always `program`. + - `pattern: string` - - `"program"` + The pattern or text to search for within the page. - - `ProgramOutput object { id, call_id, result, 2 more }` + - `type: "find_in_page"` - - `id: string` + The action type. - The unique ID of the program output item. + - `"find_in_page"` - - `call_id: string` + - `url: string` - The call ID of the program item. + The URL of the page searched for the pattern. - - `result: string` + - `status: "in_progress" or "searching" or "completed" or "failed"` - The result produced by the program item. + The status of the web search tool call. - - `status: "completed" or "incomplete"` + - `"in_progress"` - The terminal status of the program output item. + - `"searching"` - `"completed"` - - `"incomplete"` - - - `type: "program_output"` + - `"failed"` - The type of the item. Always `program_output`. + - `type: "web_search_call"` - - `"program_output"` + The type of the web search tool call. Always `web_search_call`. - - `ToolSearchCall object { id, arguments, call_id, 4 more }` + - `"web_search_call"` - - `id: string` + - `FunctionCall object { arguments, call_id, name, 5 more }` - The unique ID of the tool search call item. + A tool call to run a function. See the + [function calling guide](/docs/guides/function-calling) for more information. - - `arguments: unknown` + - `arguments: string` - Arguments used for the tool search call. + A JSON string of the arguments to pass to the function. - `call_id: string` - 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"` + The unique ID of the function tool call generated by the model. - - `status: "in_progress" or "completed" or "incomplete"` + - `name: string` - The status of the tool search call item that was recorded. + The name of the function to run. - - `"in_progress"` + - `type: "function_call"` - - `"completed"` + The type of the function tool call. Always `function_call`. - - `"incomplete"` + - `"function_call"` - - `type: "tool_search_call"` + - `id: optional string` - The type of the item. Always `tool_search_call`. + The unique ID of the function tool call. - - `"tool_search_call"` + - `caller: optional object { type } or object { caller_id, type }` - - `created_by: optional string` + The execution context that produced this tool call. - The identifier of the actor that created the item. + - `Direct object { type }` - - `ToolSearchOutput object { id, call_id, execution, 4 more }` + - `type: "direct"` - - `id: string` + - `"direct"` - The unique ID of the tool search output item. + - `Program object { caller_id, type }` - - `call_id: string` + - `caller_id: string` - The unique ID of the tool search call generated by the model. + The call ID of the program item that produced this tool call. - - `execution: "server" or "client"` + - `type: "program"` - Whether tool search was executed by the server or by the client. + - `"program"` - - `"server"` + - `namespace: optional string` - - `"client"` + The namespace of the function to run. - - `status: "in_progress" or "completed" or "incomplete"` + - `status: optional "in_progress" or "completed" or "incomplete"` - The status of the tool search output item that was recorded. + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - `"in_progress"` @@ -10711,78 +10433,359 @@ as input for the model's response. - `"incomplete"` - - `tools: array of object { name, parameters, strict, 5 more } or object { type, vector_store_ids, filters, 2 more } or object { type } or 13 more` + - `FunctionCallOutput object { call_id, output, type, 3 more }` - The loaded tool definitions returned by tool search. + The output of a function tool call. - - `Function object { name, parameters, strict, 5 more }` + - `call_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). + The unique ID of the function tool call generated by the model. - - `name: string` + - `output: string or array of ResponseInputTextContent or ResponseInputImageContent or ResponseInputFileContent` - The name of the function to call. + Text, image, or file output of the function tool call. - - `parameters: map[unknown]` + - `string` - A JSON schema object describing the parameters of the function. + A JSON string of the output of the function tool call. - - `strict: boolean` + - `array of ResponseInputTextContent or ResponseInputImageContent or ResponseInputFileContent` - Whether strict parameter validation is enforced for this function tool. + An array of content outputs (text, image, file) for the function tool call. - - `type: "function"` + - `ResponseInputTextContent object { text, type, prompt_cache_breakpoint }` - The type of the function tool. Always `function`. + A text input to the model. - - `"function"` + - `text: string` - - `allowed_callers: optional array of "direct" or "programmatic"` + The text input to the model. - The tool invocation context(s). + - `type: "input_text"` - - `"direct"` + The type of the input item. Always `input_text`. - - `"programmatic"` + - `"input_text"` - - `defer_loading: optional boolean` + - `prompt_cache_breakpoint: optional object { mode }` - Whether this function is deferred and loaded via tool search. + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - `description: optional string` + - `mode: "explicit"` - A description of the function. Used by the model to determine whether or not to call the function. + The breakpoint mode. Always `explicit`. - - `output_schema: optional map[unknown]` + - `"explicit"` - A JSON schema object describing the JSON value encoded in string outputs for this function. + - `ResponseInputImageContent object { type, detail, file_id, 2 more }` - - `FileSearch object { type, vector_store_ids, filters, 2 more }` + An image input to the model. Learn about [image inputs](/docs/guides/vision) - 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: "input_image"` - - `type: "file_search"` + The type of the input item. Always `input_image`. - The type of the file search tool. Always `file_search`. + - `"input_image"` - - `"file_search"` + - `detail: optional "low" or "high" or "auto" or "original"` - - `vector_store_ids: array of string` + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - The IDs of the vector stores to search. + - `"low"` - - `filters: optional ComparisonFilter or CompoundFilter` + - `"high"` - A filter to apply. + - `"auto"` - - `ComparisonFilter object { key, type, value }` + - `"original"` - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + - `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. + + - `prompt_cache_breakpoint: optional object { mode }` + + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + + - `mode: "explicit"` + + The breakpoint mode. Always `explicit`. + + - `"explicit"` + + - `ResponseInputFileContent object { type, detail, file_data, 4 more }` + + A file input to the model. + + - `type: "input_file"` + + The type of the input item. Always `input_file`. + + - `"input_file"` + + - `detail: optional "auto" or "low" or "high"` + + The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. + + - `"auto"` + + - `"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. + + - `prompt_cache_breakpoint: optional object { mode }` + + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + + - `mode: "explicit"` + + The breakpoint mode. Always `explicit`. + + - `"explicit"` + + - `type: "function_call_output"` + + The type of the function tool call output. Always `function_call_output`. + + - `"function_call_output"` + + - `id: optional string` + + The unique ID of the function tool call output. Populated when this item is returned via API. + + - `caller: optional object { type } or object { caller_id, type }` + + The execution context that produced this tool call. + + - `Direct object { type }` + + - `type: "direct"` + + The caller type. Always `direct`. + + - `"direct"` + + - `Program object { caller_id, type }` + + - `caller_id: string` + + The call ID of the program item that produced this tool call. + + - `type: "program"` + + The caller type. Always `program`. + + - `"program"` + + - `status: optional "in_progress" or "completed" or "incomplete"` + + The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. + + - `"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, 5 more } or object { type, vector_store_ids, filters, 2 more } or object { type } or 13 more` + + The loaded tool definitions returned by the tool search output. + + - `Function object { name, parameters, strict, 5 more }` + + Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). + + - `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 strict parameter validation is enforced for this function tool. + + - `type: "function"` + + The type of the function tool. Always `function`. + + - `"function"` + + - `allowed_callers: optional array of "direct" or "programmatic"` + + The tool invocation context(s). + + - `"direct"` + + - `"programmatic"` + + - `defer_loading: optional boolean` + + Whether this function is deferred and loaded via tool search. + + - `description: optional string` + + A description of the function. Used by the model to determine whether or not to call the function. + + - `output_schema: optional map[unknown]` + + A JSON schema object describing the JSON value encoded in string outputs for this function. + + - `FileSearch object { type, vector_store_ids, filters, 2 more }` + + A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). + + - `type: "file_search"` + + The type of the file search tool. Always `file_search`. + + - `"file_search"` + + - `vector_store_ids: array of string` + + The IDs of the vector stores to search. + + - `filters: optional ComparisonFilter or CompoundFilter` + + A filter to apply. + + - `ComparisonFilter object { key, type, value }` + + A filter used to compare a specified attribute key to a given value using a defined comparison operation. + + - `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. @@ -11118,8 +11121,40 @@ as input for the model's response. - `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`. @@ -11300,10 +11335,128 @@ as input for the model's response. - `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, allowed_callers, 3 more }` A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) @@ -11338,6 +11491,38 @@ as input for the model's response. 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. @@ -11526,43 +11711,47 @@ as input for the model's response. - `type: "tool_search_output"` - The type of the item. Always `tool_search_output`. + The item type. Always `tool_search_output`. - `"tool_search_output"` - - `created_by: optional string` + - `id: optional string` - The identifier of the actor that created the item. + The unique ID of this tool search output. - - `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 output. - - `"system"` + - `"in_progress"` - - `"critic"` + - `"completed"` - - `"discriminator"` + - `"incomplete"` - - `"developer"` + - `AdditionalTools object { role, tools, type, id }` - - `"tool"` + - `role: "developer"` + + The role that provided the additional tools. Only `developer` is supported. + + - `"developer"` - `tools: array of object { name, parameters, strict, 5 more } or object { type, vector_store_ids, filters, 2 more } or object { type } or 13 more` - The additional tool definitions made available at this item. + A list of additional tools made available at this item. - `Function object { name, parameters, strict, 5 more }` @@ -12375,21 +12564,83 @@ as input for the model's response. - `type: "additional_tools"` - The type of the item. Always `additional_tools`. + The item type. Always `additional_tools`. - `"additional_tools"` - - `Compaction object { id, encrypted_content, type, created_by }` + - `id: optional string` - A compaction item generated by the [`v1/responses/compact` API](/docs/api-reference/responses/compact). + 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 ID of the compaction item. + 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. This is populated by default + for reasoning items returned by `POST /v1/responses` and WebSocket + `response.create` requests. + + - `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 that was produced by compaction. + The encrypted content of the compaction summary. - `type: "compaction"` @@ -12397,9 +12648,9 @@ as input for the model's response. - `"compaction"` - - `created_by: optional string` + - `id: optional string` - The identifier of the actor that created the item. + The ID of the compaction item. - `ImageGenerationCall object { id, result, status, type }` @@ -12586,13 +12837,9 @@ as input for the model's response. - `"incomplete"` - - `ShellCall object { id, action, call_id, 5 more }` - - A tool call that executes one or more shell commands in a managed environment. - - - `id: string` + - `ShellCall object { action, call_id, type, 4 more }` - The unique ID of the shell tool call. Populated when this item is returned via API. + A tool representing a request to execute one or more shell commands. - `action: object { commands, max_output_length, timeout_ms }` @@ -12600,60 +12847,30 @@ as input for the model's response. - `commands: array of string` - - `max_output_length: number` + Ordered shell commands for the execution environment to run. - Optional maximum number of characters to return from each command. + - `max_output_length: optional number` - - `timeout_ms: number` + Maximum number of UTF-8 characters to capture from combined stdout and stderr output. - Optional timeout in milliseconds for the commands. + - `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. - - `environment: ResponseLocalEnvironment or ResponseContainerReference` - - Represents the use of a local environment to perform shell actions. - - - `ResponseLocalEnvironment object { type }` - - Represents the use of a local environment to perform shell actions. - - - `type: "local"` - - The environment type. Always `local`. - - - `"local"` - - - `ResponseContainerReference object { container_id, type }` - - Represents a container created with /v1/containers. - - - `container_id: string` - - - `type: "container_reference"` - - The environment type. Always `container_reference`. - - - `"container_reference"` - - - `status: "in_progress" or "completed" or "incomplete"` - - The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. - - - `"in_progress"` - - - `"completed"` - - - `"incomplete"` - - `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. + - `caller: optional object { type } or object { caller_id, type }` The execution context that produced this tool call. @@ -12662,6 +12879,8 @@ as input for the model's response. - `type: "direct"` + The caller type. Always `direct`. + - `"direct"` - `Program object { caller_id, type }` @@ -12672,35 +12891,43 @@ as input for the model's response. - `type: "program"` + The caller type. Always `program`. + - `"program"` - - `created_by: optional string` + - `environment: optional LocalEnvironment or ContainerReference` - The ID of the entity that created this tool call. + The environment to execute the shell commands in. - - `ShellCallOutput object { id, call_id, max_output_length, 5 more }` + - `LocalEnvironment object { type, skills }` - The output of a shell tool call that was emitted. + - `ContainerReference object { container_id, type }` - - `id: string` + - `status: optional "in_progress" or "completed" or "incomplete"` - The unique ID of the shell call output. Populated when this item is returned via API. + The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. - - `call_id: string` + - `"in_progress"` - The unique ID of the shell tool call generated by the model. + - `"completed"` - - `max_output_length: number` + - `"incomplete"` - The maximum length of the shell command output. This is generated by the model and should be passed back with the raw output. + - `ShellCallOutput object { call_id, output, type, 4 more }` - - `output: array of object { outcome, stderr, stdout, created_by }` + The streamed output items emitted by a shell tool call. - An array of shell call output contents + - `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 }` - Represents either an exit outcome (with an exit code) or a timeout outcome for a shell call output chunk. + The exit or timeout outcome associated with this shell call. - `Timeout object { type }` @@ -12718,7 +12945,7 @@ as input for the model's response. - `exit_code: number` - Exit code from the shell process. + The exit code returned by the shell process. - `type: "exit"` @@ -12728,32 +12955,22 @@ as input for the model's response. - `stderr: string` - The standard error output that was captured. + Captured stderr output for the shell call. - `stdout: string` - The standard output that was captured. - - - `created_by: optional string` - - The identifier of the actor that created the item. - - - `status: "in_progress" or "completed" or "incomplete"` - - The status of the shell call output. One of `in_progress`, `completed`, or `incomplete`. - - - `"in_progress"` - - - `"completed"` - - - `"incomplete"` + Captured stdout output for the shell call. - `type: "shell_call_output"` - The type of the shell call output. Always `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. + - `caller: optional object { type } or object { caller_id, type }` The execution context that produced this tool call. @@ -12762,6 +12979,8 @@ as input for the model's response. - `type: "direct"` + The caller type. Always `direct`. + - `"direct"` - `Program object { caller_id, type }` @@ -12772,19 +12991,27 @@ as input for the model's response. - `type: "program"` + The caller type. Always `program`. + - `"program"` - - `created_by: optional string` + - `max_output_length: optional number` - The identifier of the actor that created the item. + The maximum number of UTF-8 characters captured for this shell call's combined output. - - `ApplyPatchCall object { id, call_id, operation, 4 more }` + - `status: optional "in_progress" or "completed" or "incomplete"` - A tool call that applies file diffs by creating, deleting, or updating files. + The status of the shell call output. - - `id: string` + - `"in_progress"` - The unique ID of the apply patch tool call. Populated when this item is returned via API. + - `"completed"` + + - `"incomplete"` + + - `ApplyPatchCall object { call_id, operation, status, 3 more }` + + A tool call representing a request to create, delete, or update files using diff patches. - `call_id: string` @@ -12792,55 +13019,55 @@ as input for the model's response. - `operation: object { diff, path, type } or object { path, type } or object { diff, path, type }` - One of the create_file, delete_file, or update_file operations applied via apply_patch. + The specific create, delete, or update instruction for the apply_patch tool call. - `CreateFile object { diff, path, type }` - Instruction describing how to create a file via the apply_patch tool. + Instruction for creating a new file via the apply_patch tool. - `diff: string` - Diff to apply. + Unified diff content to apply when creating the file. - `path: string` - Path of the file to create. + Path of the file to create relative to the workspace root. - `type: "create_file"` - Create a new file with the provided diff. + The operation type. Always `create_file`. - `"create_file"` - `DeleteFile object { path, type }` - Instruction describing how to delete a file via the apply_patch tool. + Instruction for deleting an existing file via the apply_patch tool. - `path: string` - Path of the file to delete. + Path of the file to delete relative to the workspace root. - `type: "delete_file"` - Delete the specified file. + The operation type. Always `delete_file`. - `"delete_file"` - `UpdateFile object { diff, path, type }` - Instruction describing how to update a file via the apply_patch tool. + Instruction for updating an existing file via the apply_patch tool. - `diff: string` - Diff to apply. + Unified diff content to apply to the existing file. - `path: string` - Path of the file to update. + Path of the file to update relative to the workspace root. - `type: "update_file"` - Update an existing file with the provided diff. + The operation type. Always `update_file`. - `"update_file"` @@ -12858,6 +13085,10 @@ as input for the model's response. - `"apply_patch_call"` + - `id: optional string` + + The unique ID of the apply patch tool call. Populated when this item is returned via API. + - `caller: optional object { type } or object { caller_id, type }` The execution context that produced this tool call. @@ -12866,6 +13097,8 @@ as input for the model's response. - `type: "direct"` + The caller type. Always `direct`. + - `"direct"` - `Program object { caller_id, type }` @@ -12876,19 +13109,13 @@ as input for the model's response. - `type: "program"` - - `"program"` - - - `created_by: optional string` - - The ID of the entity that created this tool call. - - - `ApplyPatchCallOutput object { id, call_id, status, 4 more }` + The caller type. Always `program`. - The output emitted by an apply patch tool call. + - `"program"` - - `id: string` + - `ApplyPatchCallOutput object { call_id, status, type, 3 more }` - The unique ID of the apply patch tool call output. Populated when this item is returned via API. + The streamed output emitted by an apply patch tool call. - `call_id: string` @@ -12908,6 +13135,10 @@ as input for the model's response. - `"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. + - `caller: optional object { type } or object { caller_id, type }` The execution context that produced this tool call. @@ -12916,6 +13147,8 @@ as input for the model's response. - `type: "direct"` + The caller type. Always `direct`. + - `"direct"` - `Program object { caller_id, type }` @@ -12926,68 +13159,13 @@ as input for the model's response. - `type: "program"` - - `"program"` - - - `created_by: optional string` - - The ID of the entity that created this tool call output. - - - `output: optional string` - - Optional textual output returned by the apply patch tool. - - - `McpCall object { id, arguments, name, 6 more }` - - An invocation of a tool on an MCP server. - - - `id: string` - - The unique ID of the tool call. - - - `arguments: string` - - A JSON string of the arguments passed to the tool. - - - `name: string` - - The name of the tool that was run. - - - `server_label: string` - - The label of the MCP server running the tool. - - - `type: "mcp_call"` - - The type of the item. Always `mcp_call`. - - - `"mcp_call"` - - - `approval_request_id: optional string` - - Unique identifier for the MCP tool call approval request. - Include this value in a subsequent `mcp_approval_response` input to approve or reject the corresponding tool call. - - - `error: optional string` + The caller type. Always `program`. - The error from the tool call, if any. + - `"program"` - `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"` + Optional human-readable log text from the apply patch tool (e.g., patch results or errors). - `McpListTools object { id, server_label, tools, 2 more }` @@ -13057,14 +13235,10 @@ as input for the model's response. - `"mcp_approval_request"` - - `McpApprovalResponse object { id, approval_request_id, approve, 2 more }` + - `McpApprovalResponse object { approval_request_id, approve, type, 2 more }` A response to an MCP approval request. - - `id: string` - - The unique ID of the approval response - - `approval_request_id: string` The ID of the approval request being answered. @@ -13079,65 +13253,70 @@ as input for the model's response. - `"mcp_approval_response"` + - `id: optional string` + + The unique ID of the approval response + - `reason: optional string` Optional reason for the decision. - - `CustomToolCall object { call_id, input, name, 4 more }` + - `McpCall object { id, arguments, name, 6 more }` - A call to a custom tool created by the model. + An invocation of a tool on an MCP server. - - `call_id: string` + - `id: string` - An identifier used to map this custom tool call to a tool call output. + The unique ID of the tool call. - - `input: string` + - `arguments: string` - The input for the custom tool call generated by the model. + A JSON string of the arguments passed to the tool. - `name: string` - The name of the custom tool being called. + The name of the tool that was run. - - `type: "custom_tool_call"` + - `server_label: string` - The type of the custom tool call. Always `custom_tool_call`. + The label of the MCP server running the tool. - - `"custom_tool_call"` + - `type: "mcp_call"` - - `id: optional string` + The type of the item. Always `mcp_call`. - The unique ID of the custom tool call in the OpenAI platform. + - `"mcp_call"` - - `caller: optional object { type } or object { caller_id, type }` + - `approval_request_id: optional string` - The execution context that produced this tool call. + 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. - - `Direct object { type }` + - `error: optional string` - - `type: "direct"` + The error from the tool call, if any. - - `"direct"` + - `output: optional string` - - `Program object { caller_id, type }` + The output from the tool call. - - `caller_id: string` + - `status: optional "in_progress" or "completed" or "incomplete" or 2 more` - The call ID of the program item that produced this tool call. + The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. - - `type: "program"` + - `"in_progress"` - - `"program"` + - `"completed"` - - `namespace: optional string` + - `"incomplete"` - The namespace of the custom tool being called. + - `"calling"` - - `CustomToolCallOutput object { id, call_id, output, 4 more }` + - `"failed"` - - `id: string` + - `CustomToolCallOutput object { call_id, output, type, 2 more }` - The unique ID of the custom tool call output item. + The output of a custom tool call from your code, being sent back to the model. - `call_id: string` @@ -13168,23 +13347,16 @@ as input for the model's response. A file input to the model. - - `status: "in_progress" or "completed" or "incomplete"` - - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. - - - `"in_progress"` - - - `"completed"` - - - `"incomplete"` - - `type: "custom_tool_call_output"` The type of the custom tool call output. Always `custom_tool_call_output`. - `"custom_tool_call_output"` + - `id: optional string` + + The unique ID of the custom tool call output in the OpenAI platform. + - `caller: optional object { type } or object { caller_id, type }` The execution context that produced this tool call. @@ -13209,854 +13381,801 @@ as input for the model's response. - `"program"` - - `created_by: optional string` + - `CustomToolCall object { call_id, input, name, 4 more }` - The identifier of the actor that created the item. + A call to a custom tool created by the model. - - `parallel_tool_calls: boolean` + - `call_id: string` - Whether to allow the model to run tool calls in parallel. + An identifier used to map this custom tool call to a tool call output. - - `temperature: number` + - `input: string` - What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. - We generally recommend altering this or `top_p` but not both. + The input for the custom tool call generated by the model. - - `tool_choice: ToolChoiceOptions or ToolChoiceAllowed or ToolChoiceTypes or 6 more` + - `name: string` - How the model should select which tool (or tools) to use when generating - a response. See the `tools` parameter to see how to specify which tools - the model can call. + The name of the custom tool being called. - - `ToolChoiceOptions = "none" or "auto" or "required"` + - `type: "custom_tool_call"` - Controls which (if any) tool is called by the model. + The type of the custom tool call. Always `custom_tool_call`. - `none` means the model will not call any tool and instead generates a message. + - `"custom_tool_call"` - `auto` means the model can pick between generating a message or calling one or - more tools. + - `id: optional string` - `required` means the model must call one or more tools. + The unique ID of the custom tool call in the OpenAI platform. - - `"none"` + - `caller: optional object { type } or object { caller_id, type }` - - `"auto"` + The execution context that produced this tool call. - - `"required"` + - `Direct object { type }` - - `ToolChoiceAllowed object { mode, tools, type }` + - `type: "direct"` - Constrains the tools available to the model to a pre-defined set. + - `"direct"` - - `mode: "auto" or "required"` + - `Program object { caller_id, type }` - Constrains the tools available to the model to a pre-defined set. + - `caller_id: string` - `auto` allows the model to pick from among the allowed tools and generate a - message. + The call ID of the program item that produced this tool call. - `required` requires the model to call one or more of the allowed tools. + - `type: "program"` - - `"auto"` + - `"program"` - - `"required"` + - `namespace: optional string` - - `tools: array of map[unknown]` + The namespace of the custom tool being called. - A list of tool definitions that the model should be allowed to call. + - `CompactionTrigger object { type }` - For the Responses API, the list of tool definitions might look like: + Compacts the current context. Must be the final input item. - ```json - [ - { "type": "function", "name": "get_weather" }, - { "type": "mcp", "server_label": "deepwiki" }, - { "type": "image_generation" } - ] - ``` + - `type: "compaction_trigger"` - - `type: "allowed_tools"` + The type of the item. Always `compaction_trigger`. - Allowed tool configuration type. Always `allowed_tools`. + - `"compaction_trigger"` - - `"allowed_tools"` + - `ItemReference object { id, type }` - - `ToolChoiceTypes object { type }` + An internal identifier for an item to reference. - Indicates that the model should use a built-in tool to generate a response. - [Learn more about built-in tools](/docs/guides/tools). + - `id: string` - - `type: "file_search" or "web_search_preview" or "computer" or 5 more` + The ID of the item to reference. - The type of hosted tool the model should to use. Learn more about - [built-in tools](/docs/guides/tools). + - `type: optional "item_reference"` - Allowed values are: + The type of item to reference. Always `item_reference`. - - `file_search` - - `web_search_preview` - - `computer` - - `computer_use_preview` - - `computer_use` - - `code_interpreter` - - `image_generation` + - `"item_reference"` - - `"file_search"` + - `Program object { id, call_id, code, 2 more }` - - `"web_search_preview"` + - `id: string` - - `"computer"` + The unique ID of this program item. - - `"computer_use_preview"` + - `call_id: string` - - `"computer_use"` + The stable call ID of the program item. - - `"web_search_preview_2025_03_11"` + - `code: string` - - `"image_generation"` + The JavaScript source executed by programmatic tool calling. - - `"code_interpreter"` + - `fingerprint: string` - - `ToolChoiceFunction object { name, type }` + Opaque program replay fingerprint that must be round-tripped. - Use this option to force the model to call a specific function. + - `type: "program"` - - `name: string` + The item type. Always `program`. - The name of the function to call. + - `"program"` - - `type: "function"` + - `ProgramOutput object { id, call_id, result, 2 more }` - For function calling, the type is always `function`. + - `id: string` - - `"function"` + The unique ID of this program output item. - - `ToolChoiceMcp object { server_label, type, name }` + - `call_id: string` - Use this option to force the model to call a specific tool on a remote MCP server. + The call ID of the program item. - - `server_label: string` + - `result: string` - The label of the MCP server to use. + The result produced by the program item. - - `type: "mcp"` + - `status: "completed" or "incomplete"` - For MCP tools, the type is always `mcp`. + The terminal status of the program output. - - `"mcp"` + - `"completed"` - - `name: optional string` + - `"incomplete"` - The name of the tool to call on the server. + - `type: "program_output"` - - `ToolChoiceCustom object { name, type }` + The item type. Always `program_output`. - Use this option to force the model to call a specific custom tool. + - `"program_output"` - - `name: string` +- `instructions: optional string` - The name of the custom tool to call. + A system (or developer) message inserted into the model's context. + When used along with `previous_response_id`, the instructions from a previous response will not be carried over to the next response. This makes it simple to swap out system (or developer) messages in new responses. - - `type: "custom"` +- `previous_response_id: optional string` - For custom tool calling, the type is always `custom`. + The unique ID of the previous response to the model. Use this to create multi-turn conversations. Learn more about [conversation state](/docs/guides/conversation-state). Cannot be used in conjunction with `conversation`. - - `"custom"` +- `prompt_cache_key: optional string` - - `SpecificProgrammaticToolCallingParam object { type }` + A key to use when reading from or writing to the prompt cache. - - `type: "programmatic_tool_calling"` +- `prompt_cache_options: optional object { mode, ttl }` - The tool to call. Always `programmatic_tool_calling`. + Options for prompt caching. Supported for `gpt-5.6` and later models. By default, OpenAI automatically chooses one implicit cache breakpoint. You can add explicit breakpoints to content blocks with `prompt_cache_breakpoint`. Each request can write up to four breakpoints. For cache matching, OpenAI considers up to the latest 80 breakpoints in the conversation, without a content-block lookback limit. Set `mode` to `explicit` to disable the implicit breakpoint. The `ttl` defaults to `30m`, which is currently the only supported value. See the [prompt caching guide](/docs/guides/prompt-caching) for current details. - - `"programmatic_tool_calling"` + - `mode: optional "implicit" or "explicit"` - - `ToolChoiceApplyPatch object { type }` + Controls whether OpenAI automatically creates an implicit cache breakpoint. Defaults to `implicit`. With `implicit`, OpenAI creates one implicit breakpoint and writes up to the latest three explicit breakpoints in the request. With `explicit`, OpenAI does not create an implicit breakpoint and writes up to the latest four explicit breakpoints. If there are no explicit breakpoints, the request does not use prompt caching. - Forces the model to call the apply_patch tool when executing a tool call. + - `"implicit"` - - `type: "apply_patch"` + - `"explicit"` - The tool to call. Always `apply_patch`. + - `ttl: optional "30m"` - - `"apply_patch"` + The minimum lifetime applied to every implicit and explicit cache breakpoint written by the request. Defaults to `30m`, which is currently the only supported value. The backend may retain cache entries for longer. - - `ToolChoiceShell object { type }` + - `"30m"` - Forces the model to call the shell tool when a tool call is required. +- `prompt_cache_retention: optional "in_memory" or "24h"` - - `type: "shell"` + How long to retain a prompt cache entry created by this request. - The tool to call. Always `shell`. + - `"in_memory"` - - `"shell"` + - `"24h"` - - `tools: array of object { name, parameters, strict, 5 more } or object { type, vector_store_ids, filters, 2 more } or object { type } or 13 more` +- `service_tier: optional "auto" or "default" or "flex" or "priority"` - An array of tools the model may call while generating a response. You - can specify which tool to use by setting the `tool_choice` parameter. + The service tier to use for this request. - We support the following categories of tools: + - `"auto"` - - **Built-in tools**: Tools that are provided by OpenAI that extend the - model's capabilities, like [web search](/docs/guides/tools-web-search) - or [file search](/docs/guides/tools-file-search). Learn more about - [built-in tools](/docs/guides/tools). - - **MCP Tools**: Integrations with third-party systems via custom MCP servers - or predefined connectors such as Google Drive and SharePoint. Learn more about - [MCP Tools](/docs/guides/tools-connectors-mcp). - - **Function calls (custom tools)**: Functions that are defined by you, - enabling the model to call your own code with strongly typed arguments - and outputs. Learn more about - [function calling](/docs/guides/function-calling). You can also use - custom tools to call your own code. + - `"default"` - - `Function object { name, parameters, strict, 5 more }` + - `"flex"` - 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). + - `"priority"` - - `name: string` +### Returns - The name of the function to call. +- `CompactedResponse object { id, created_at, object, 2 more }` - - `parameters: map[unknown]` + - `id: string` - A JSON schema object describing the parameters of the function. + The unique identifier for the compacted response. - - `strict: boolean` + - `created_at: number` - Whether strict parameter validation is enforced for this function tool. + Unix timestamp (in seconds) when the compacted conversation was created. - - `type: "function"` + - `object: "response.compaction"` - The type of the function tool. Always `function`. + The object type. Always `response.compaction`. - - `"function"` + - `"response.compaction"` - - `allowed_callers: optional array of "direct" or "programmatic"` + - `output: array of Message or object { id, call_id, code, 2 more } or object { id, call_id, result, 2 more } or 25 more` - The tool invocation context(s). + The compacted list of output items. - - `"direct"` + - `Message object { id, content, role, 3 more }` - - `"programmatic"` + A message to or from the model. - - `defer_loading: optional boolean` + - `id: string` - Whether this function is deferred and loaded via tool search. + The unique ID of the message. - - `description: optional string` + - `content: array of ResponseInputText or ResponseOutputText or TextContent or 6 more` - A description of the function. Used by the model to determine whether or not to call the function. + The content of the message - - `output_schema: optional map[unknown]` + - `ResponseInputText object { text, type, prompt_cache_breakpoint }` - A JSON schema object describing the JSON value encoded in string outputs for this function. + A text input to the model. - - `FileSearch object { type, vector_store_ids, filters, 2 more }` + - `text: 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 text input to the model. - - `type: "file_search"` + - `type: "input_text"` - The type of the file search tool. Always `file_search`. + The type of the input item. Always `input_text`. - - `"file_search"` + - `"input_text"` - - `vector_store_ids: array of string` + - `prompt_cache_breakpoint: optional object { mode }` - The IDs of the vector stores to search. + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - `filters: optional ComparisonFilter or CompoundFilter` + - `mode: "explicit"` - A filter to apply. + The breakpoint mode. Always `explicit`. - - `ComparisonFilter object { key, type, value }` + - `"explicit"` - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + - `ResponseOutputText object { annotations, logprobs, text, type }` - - `CompoundFilter object { filters, type }` + A text output from the model. - Combine multiple filters using `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 }` - - `max_num_results: optional number` + The annotations of the text output. - The maximum number of results to return. This number should be between 1 and 50 inclusive. + - `FileCitation object { file_id, filename, index, type }` - - `ranking_options: optional object { hybrid_search, ranker, score_threshold }` + A citation to a file. - Ranking options for search. + - `file_id: string` - - `hybrid_search: optional object { embedding_weight, text_weight }` + The ID of the file. - Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. + - `filename: string` - - `embedding_weight: number` + The filename of the file cited. - The weight of the embedding in the reciprocal ranking fusion. + - `index: number` - - `text_weight: number` + The index of the file in the list of files. - The weight of the text in the reciprocal ranking fusion. + - `type: "file_citation"` - - `ranker: optional "auto" or "default-2024-11-15"` + The type of the file citation. Always `file_citation`. - The ranker to use for the file search. + - `"file_citation"` - - `"auto"` + - `URLCitation object { end_index, start_index, title, 2 more }` - - `"default-2024-11-15"` + A citation for a web resource used to generate a model response. - - `score_threshold: optional number` + - `end_index: 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. + The index of the last character of the URL citation in the message. - - `Computer object { type }` + - `start_index: number` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + The index of the first character of the URL citation in the message. - - `type: "computer"` + - `title: string` - The type of the computer tool. Always `computer`. + The title of the web resource. - - `"computer"` + - `type: "url_citation"` - - `ComputerUsePreview object { display_height, display_width, environment, type }` + The type of the URL citation. Always `url_citation`. - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `"url_citation"` - - `display_height: number` + - `url: string` - The height of the computer display. + The URL of the web resource. - - `display_width: number` + - `ContainerFileCitation object { container_id, end_index, file_id, 3 more }` - The width of the computer display. + A citation for a container file used to generate a model response. - - `environment: "windows" or "mac" or "linux" or 2 more` + - `container_id: string` - The type of computer environment to control. + The ID of the container file. - - `"windows"` + - `end_index: number` - - `"mac"` + The index of the last character of the container file citation in the message. - - `"linux"` + - `file_id: string` - - `"ubuntu"` + The ID of the file. - - `"browser"` + - `filename: string` - - `type: "computer_use_preview"` + The filename of the container file cited. - The type of the computer use tool. Always `computer_use_preview`. + - `start_index: number` - - `"computer_use_preview"` + The index of the first character of the container file citation in the message. - - `WebSearch object { type, filters, search_context_size, user_location }` + - `type: "container_file_citation"` - Search the Internet for sources related to the prompt. Learn more about the - [web search tool](/docs/guides/tools-web-search). + The type of the container file citation. Always `container_file_citation`. - - `type: "web_search" or "web_search_2025_08_26"` + - `"container_file_citation"` - The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. + - `FilePath object { file_id, index, type }` - - `"web_search"` + A path to a file. - - `"web_search_2025_08_26"` + - `file_id: string` - - `filters: optional object { allowed_domains }` + The ID of the file. - Filters for the search. + - `index: number` - - `allowed_domains: optional array of string` + The index of the file in the list of files. - Allowed domains for the search. If not provided, all domains are allowed. - Subdomains of the provided domains are allowed as well. + - `type: "file_path"` - Example: `["pubmed.ncbi.nlm.nih.gov"]` + The type of the file path. Always `file_path`. - - `search_context_size: optional "low" or "medium" or "high"` + - `"file_path"` - 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. + - `logprobs: array of object { token, bytes, logprob, top_logprobs }` - - `"low"` + - `token: string` - - `"medium"` + - `bytes: array of number` - - `"high"` + - `logprob: number` - - `user_location: optional object { city, country, region, 2 more }` + - `top_logprobs: array of object { token, bytes, logprob }` - The approximate location of the user. + - `token: string` - - `city: optional string` + - `bytes: array of number` - Free text input for the city of the user, e.g. `San Francisco`. + - `logprob: number` - - `country: optional string` + - `text: string` - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + The text output from the model. - - `region: optional string` + - `type: "output_text"` - Free text input for the region of the user, e.g. `California`. + The type of the output text. Always `output_text`. - - `timezone: optional string` + - `"output_text"` - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + - `TextContent object { text, type }` - - `type: optional "approximate"` + A text content. - The type of location approximation. Always `approximate`. + - `text: string` - - `"approximate"` + - `type: "text"` - - `Mcp object { server_label, type, allowed_callers, 9 more }` + - `"text"` - Give the model access to additional tools via remote Model Context Protocol - (MCP) servers. [Learn more about MCP](/docs/guides/tools-remote-mcp). + - `SummaryTextContent object { text, type }` - - `server_label: string` + A summary text from the model. - A label for this MCP server, used to identify it in tool calls. + - `text: string` - - `type: "mcp"` + A summary of the reasoning output from the model so far. - The type of the MCP tool. Always `mcp`. + - `type: "summary_text"` - - `"mcp"` + The type of the object. Always `summary_text`. - - `allowed_callers: optional array of "direct" or "programmatic"` + - `"summary_text"` - The tool invocation context(s). + - `ReasoningText object { text, type }` - - `"direct"` + Reasoning text from the model. - - `"programmatic"` + - `text: string` - - `allowed_tools: optional array of string or object { read_only, tool_names }` + The reasoning text from the model. - List of allowed tool names or a filter object. + - `type: "reasoning_text"` - - `McpAllowedTools = array of string` + The type of the reasoning text. Always `reasoning_text`. - A string array of allowed tool names + - `"reasoning_text"` - - `McpToolFilter object { read_only, tool_names }` + - `ResponseOutputRefusal object { refusal, type }` - A filter object to specify which tools are allowed. + A refusal from the model. - - `read_only: optional boolean` + - `refusal: 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 refusal explanation from the model. - - `tool_names: optional array of string` + - `type: "refusal"` - List of allowed tool names. + The type of the refusal. Always `refusal`. - - `authorization: optional string` + - `"refusal"` - 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. + - `ResponseInputImage object { detail, type, file_id, 2 more }` - - `connector_id: optional "connector_dropbox" or "connector_gmail" or "connector_googlecalendar" or 5 more` + An image input to the model. Learn about [image inputs](/docs/guides/vision). - Identifier for service connectors, like those available in ChatGPT. One of - `server_url`, `connector_id`, or `tunnel_id` must be provided. Learn more - about service connectors [here](/docs/guides/tools-remote-mcp#connectors). + - `detail: "low" or "high" or "auto" or "original"` - Currently supported `connector_id` values are: + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - - 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` + - `"low"` - - `"connector_dropbox"` + - `"high"` - - `"connector_gmail"` + - `"auto"` - - `"connector_googlecalendar"` + - `"original"` - - `"connector_googledrive"` + - `type: "input_image"` - - `"connector_microsoftteams"` + The type of the input item. Always `input_image`. - - `"connector_outlookcalendar"` + - `"input_image"` - - `"connector_outlookemail"` + - `file_id: optional string` - - `"connector_sharepoint"` + The ID of the file to be sent to the model. - - `defer_loading: optional boolean` + - `image_url: optional string` - Whether this MCP tool is deferred and discovered via tool search. + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - - `headers: optional map[string]` + - `prompt_cache_breakpoint: optional object { mode }` - Optional HTTP headers to send to the MCP server. Use for authentication - or other purposes. + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - `require_approval: optional object { always, never } or "always" or "never"` + - `mode: "explicit"` - Specify which of the MCP server's tools require approval. + The breakpoint mode. Always `explicit`. - - `McpToolApprovalFilter object { always, never }` + - `"explicit"` - Specify which of the MCP server's tools require approval. Can be - `always`, `never`, or a filter object associated with tools - that require approval. + - `ComputerScreenshotContent object { detail, file_id, image_url, 2 more }` - - `always: optional object { read_only, tool_names }` + A screenshot of a computer. - A filter object to specify which tools are allowed. + - `detail: "low" or "high" or "auto" or "original"` - - `read_only: optional boolean` + The detail level of the screenshot image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - 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. + - `"auto"` - - `never: optional object { read_only, tool_names }` + - `"original"` - A filter object to specify which tools are allowed. + - `file_id: string` - - `read_only: optional boolean` + The identifier of an uploaded file that contains the screenshot. - 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. + - `image_url: string` - - `tool_names: optional array of string` + The URL of the screenshot image. - List of allowed tool names. + - `type: "computer_screenshot"` - - `McpToolApprovalSetting = "always" or "never"` + Specifies the event type. For a computer screenshot, this property is always set to `computer_screenshot`. - 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. + - `"computer_screenshot"` - - `"always"` + - `prompt_cache_breakpoint: optional object { mode }` - - `"never"` + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - `server_description: optional string` + - `mode: "explicit"` - Optional description of the MCP server, used to provide more context. + The breakpoint mode. Always `explicit`. - - `server_url: optional string` + - `"explicit"` - The URL for the MCP server. One of `server_url`, `connector_id`, or - `tunnel_id` must be provided. + - `ResponseInputFile object { type, detail, file_data, 4 more }` - - `tunnel_id: optional string` + A file input to the model. - The Secure MCP Tunnel ID to use instead of a direct server URL. One of - `server_url`, `connector_id`, or `tunnel_id` must be provided. + - `type: "input_file"` - - `CodeInterpreter object { container, type, allowed_callers }` + The type of the input item. Always `input_file`. - A tool that runs Python code to help generate a response to a prompt. + - `"input_file"` - - `container: string or object { type, file_ids, memory_limit, network_policy }` + - `detail: optional "auto" or "low" or "high"` - 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 detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. - - `string` + - `"auto"` - The container ID. + - `"low"` - - `CodeInterpreterToolAuto object { type, file_ids, memory_limit, network_policy }` + - `"high"` - Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. + - `file_data: optional string` - - `type: "auto"` + The content of the file to be sent to the model. - Always `auto`. + - `file_id: optional string` - - `"auto"` + The ID of the file to be sent to the model. - - `file_ids: optional array of string` + - `file_url: optional string` - An optional list of uploaded files to make available to your code. + The URL of the file to be sent to the model. - - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` + - `filename: optional string` - The memory limit for the code interpreter container. + The name of the file to be sent to the model. - - `"1g"` + - `prompt_cache_breakpoint: optional object { mode }` - - `"4g"` + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - `"16g"` + - `mode: "explicit"` - - `"64g"` + The breakpoint mode. Always `explicit`. - - `network_policy: optional ContainerNetworkPolicyDisabled or ContainerNetworkPolicyAllowlist` + - `"explicit"` - Network access policy for the container. + - `role: "unknown" or "user" or "assistant" or 5 more` - - `ContainerNetworkPolicyDisabled object { type }` + The role of the message. One of `unknown`, `user`, `assistant`, `system`, `critic`, `discriminator`, `developer`, or `tool`. - - `ContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` + - `"unknown"` - - `type: "code_interpreter"` + - `"user"` - The type of the code interpreter tool. Always `code_interpreter`. + - `"assistant"` - - `"code_interpreter"` + - `"system"` - - `allowed_callers: optional array of "direct" or "programmatic"` + - `"critic"` - The tool invocation context(s). + - `"discriminator"` - - `"direct"` + - `"developer"` - - `"programmatic"` + - `"tool"` - - `ProgrammaticToolCalling object { type }` + - `status: "in_progress" or "completed" or "incomplete"` - - `type: "programmatic_tool_calling"` + The status of item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. - The type of the tool. Always `programmatic_tool_calling`. + - `"in_progress"` - - `"programmatic_tool_calling"` + - `"completed"` - - `ImageGeneration object { type, action, background, 9 more }` + - `"incomplete"` - A tool that generates images using the GPT image models. + - `type: "message"` - - `type: "image_generation"` + The type of the message. Always set to `message`. - The type of the image generation tool. Always `image_generation`. + - `"message"` - - `"image_generation"` + - `phase: optional "commentary" or "final_answer"` - - `action: optional "generate" or "edit" or "auto"` + 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. - Whether to generate a new image or edit an existing image. Default: `auto`. + - `"commentary"` - - `"generate"` + - `"final_answer"` - - `"edit"` + - `Program object { id, call_id, code, 2 more }` - - `"auto"` + - `id: string` - - `background: optional "transparent" or "opaque" or "auto"` + The unique ID of the program item. - Background type for the generated image. One of `transparent`, - `opaque`, or `auto`. Default: `auto`. + - `call_id: string` - - `"transparent"` + The stable call ID of the program item. - - `"opaque"` + - `code: string` - - `"auto"` + The JavaScript source executed by programmatic tool calling. - - `input_fidelity: optional "high" or "low"` + - `fingerprint: 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`. + Opaque program replay fingerprint that must be round-tripped. - - `"high"` + - `type: "program"` - - `"low"` + The type of the item. Always `program`. - - `input_image_mask: optional object { file_id, image_url }` + - `"program"` - Optional mask for inpainting. Contains `image_url` - (string, optional) and `file_id` (string, optional). + - `ProgramOutput object { id, call_id, result, 2 more }` - - `file_id: optional string` + - `id: string` - File ID for the mask image. + The unique ID of the program output item. - - `image_url: optional string` + - `call_id: string` - Base64-encoded mask image. + The call ID of the program item. - - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` + - `result: string` - The image generation model to use. Default: `gpt-image-1`. + The result produced by the program item. - - `string` + - `status: "completed" or "incomplete"` - - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` + The terminal status of the program output item. - The image generation model to use. Default: `gpt-image-1`. + - `"completed"` - - `"gpt-image-1"` + - `"incomplete"` - - `"gpt-image-1-mini"` + - `type: "program_output"` - - `"gpt-image-1.5"` + The type of the item. Always `program_output`. - - `moderation: optional "auto" or "low"` + - `"program_output"` - Moderation level for the generated image. Default: `auto`. + - `FunctionCall object { arguments, call_id, name, 5 more }` - - `"auto"` + A tool call to run a function. See the + [function calling guide](/docs/guides/function-calling) for more information. - - `"low"` + - `arguments: string` - - `output_compression: optional number` + A JSON string of the arguments to pass to the function. - Compression level for the output image. Default: 100. + - `call_id: string` - - `output_format: optional "png" or "webp" or "jpeg"` + The unique ID of the function tool call generated by the model. - The output format of the generated image. One of `png`, `webp`, or - `jpeg`. Default: `png`. + - `name: string` - - `"png"` + The name of the function to run. - - `"webp"` + - `type: "function_call"` - - `"jpeg"` + The type of the function tool call. Always `function_call`. - - `partial_images: optional number` + - `"function_call"` - Number of partial images to generate in streaming mode, from 0 (default value) to 3. + - `id: optional string` - - `quality: optional "low" or "medium" or "high" or "auto"` + The unique ID of the function tool call. - The quality of the generated image. One of `low`, `medium`, `high`, - or `auto`. Default: `auto`. + - `caller: optional object { type } or object { caller_id, type }` - - `"low"` + The execution context that produced this tool call. - - `"medium"` + - `Direct object { type }` - - `"high"` + - `type: "direct"` - - `"auto"` + - `"direct"` - - `size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or "auto"` + - `Program object { caller_id, 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`. + - `caller_id: string` - - `string` + The call ID of the program item that produced this tool call. - - `"1024x1024" or "1024x1536" or "1536x1024" or "auto"` + - `type: "program"` - 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`. + - `"program"` - - `"1024x1024"` + - `namespace: optional string` - - `"1024x1536"` + The namespace of the function to run. - - `"1536x1024"` + - `status: optional "in_progress" or "completed" or "incomplete"` - - `"auto"` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `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`. + - `ToolSearchCall object { id, arguments, call_id, 4 more }` - - `"local_shell"` + - `id: string` - - `Shell object { type, allowed_callers, environment }` + The unique ID of the tool search call item. - A tool that allows the model to execute shell commands. + - `arguments: unknown` - - `type: "shell"` + Arguments used for the tool search call. - The type of the shell tool. Always `shell`. + - `call_id: string` - - `"shell"` + The unique ID of the tool search call generated by the model. - - `allowed_callers: optional array of "direct" or "programmatic"` + - `execution: "server" or "client"` - The tool invocation context(s). + Whether tool search was executed by the server or by the client. - - `"direct"` + - `"server"` - - `"programmatic"` + - `"client"` - - `environment: optional ContainerAuto or LocalEnvironment or ContainerReference` + - `status: "in_progress" or "completed" or "incomplete"` - - `ContainerAuto object { type, file_ids, memory_limit, 2 more }` + The status of the tool search call item that was recorded. - - `LocalEnvironment object { type, skills }` + - `"in_progress"` - - `ContainerReference object { container_id, type }` + - `"completed"` - - `Custom object { name, type, allowed_callers, 3 more }` + - `"incomplete"` - A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) + - `type: "tool_search_call"` - - `name: string` + The type of the item. Always `tool_search_call`. - The name of the custom tool, used to identify it in tool calls. + - `"tool_search_call"` - - `type: "custom"` + - `created_by: optional string` - The type of the custom tool. Always `custom`. + The identifier of the actor that created the item. - - `"custom"` + - `ToolSearchOutput object { id, call_id, execution, 4 more }` - - `allowed_callers: optional array of "direct" or "programmatic"` + - `id: string` - The tool invocation context(s). + The unique ID of the tool search output item. - - `"direct"` + - `call_id: string` - - `"programmatic"` + The unique ID of the tool search call generated by the model. - - `defer_loading: optional boolean` + - `execution: "server" or "client"` - Whether this tool should be deferred and discovered via tool search. + Whether tool search was executed by the server or by the client. - - `description: optional string` + - `"server"` - Optional description of the custom tool, used to provide more context. + - `"client"` - - `format: optional CustomToolInputFormat` + - `status: "in_progress" or "completed" or "incomplete"` - The input format for the custom tool. Default is unconstrained text. + The status of the tool search output item that was recorded. - - `Namespace object { description, name, tools, type }` + - `"in_progress"` - Groups function/custom tools under a shared namespace. + - `"completed"` - - `description: string` + - `"incomplete"` - A description of the namespace shown to the model. + - `tools: array of object { name, parameters, strict, 5 more } or object { type, vector_store_ids, filters, 2 more } or object { type } or 13 more` + + The loaded tool definitions returned by tool search. + + - `Function object { name, parameters, strict, 5 more }` + + Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). - `name: string` - The namespace name used in tool calls (for example, `crm`). + The name of the function to call. - - `tools: array of object { name, type, allowed_callers, 5 more } or object { name, type, allowed_callers, 3 more }` + - `parameters: map[unknown]` - The function/custom tools available inside this namespace. + A JSON schema object describing the parameters of the function. - - `Function object { name, type, allowed_callers, 5 more }` + - `strict: boolean` - - `name: string` + Whether strict parameter validation is enforced for this function tool. - `type: "function"` + The type of the function tool. Always `function`. + - `"function"` - `allowed_callers: optional array of "direct" or "programmatic"` @@ -14069,618 +14188,599 @@ as input for the model's response. - `defer_loading: optional boolean` - Whether this function should be deferred and discovered via tool search. + 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. + - `output_schema: optional map[unknown]` - A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. + A JSON schema object describing the JSON value encoded in string outputs for this function. - - `parameters: optional unknown` + - `FileSearch object { type, vector_store_ids, filters, 2 more }` - - `strict: optional boolean` + 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). - Whether to enforce strict parameter validation. If omitted, Responses attempts to use strict validation when the schema is compatible, and falls back to non-strict validation otherwise. + - `type: "file_search"` - - `Custom object { name, type, allowed_callers, 3 more }` + The type of the file search tool. Always `file_search`. - A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) + - `"file_search"` - - `name: string` + - `vector_store_ids: array of string` - The name of the custom tool, used to identify it in tool calls. + The IDs of the vector stores to search. - - `type: "custom"` + - `filters: optional ComparisonFilter or CompoundFilter` - The type of the custom tool. Always `custom`. + A filter to apply. - - `"custom"` + - `ComparisonFilter object { key, type, value }` - - `allowed_callers: optional array of "direct" or "programmatic"` + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - The tool invocation context(s). + - `key: string` - - `"direct"` + The key to compare against the value. - - `"programmatic"` + - `type: "eq" or "ne" or "gt" or 5 more` - - `defer_loading: optional boolean` + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - Whether this tool should be deferred and discovered via tool search. + - `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 - - `description: optional string` + - `"eq"` - Optional description of the custom tool, used to provide more context. + - `"ne"` - - `format: optional CustomToolInputFormat` + - `"gt"` - The input format for the custom tool. Default is unconstrained text. + - `"gte"` - - `type: "namespace"` + - `"lt"` - The type of the tool. Always `namespace`. + - `"lte"` - - `"namespace"` + - `"in"` - - `ToolSearch object { type, description, execution, parameters }` + - `"nin"` - Hosted or BYOT tool search configuration for deferred tools. + - `value: string or number or boolean or array of string or number` - - `type: "tool_search"` + The value to compare against the attribute key; supports string, number, or boolean types. - The type of the tool. Always `tool_search`. + - `string` - - `"tool_search"` + - `number` - - `description: optional string` + - `boolean` - Description shown to the model for a client-executed tool search tool. + - `array of string or number` - - `execution: optional "server" or "client"` + - `string` - Whether tool search is executed by the server or by the client. + - `number` - - `"server"` + - `CompoundFilter object { filters, type }` - - `"client"` + Combine multiple filters using `and` or `or`. - - `parameters: optional unknown` + - `filters: array of ComparisonFilter or unknown` - Parameter schema for a client-executed tool search tool. + Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. - - `WebSearchPreview object { type, search_content_types, search_context_size, user_location }` + - `ComparisonFilter object { key, type, value }` - 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 filter used to compare a specified attribute key to a given value using a defined comparison operation. - - `type: "web_search_preview" or "web_search_preview_2025_03_11"` + - `unknown` - The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. + - `type: "and" or "or"` - - `"web_search_preview"` + Type of operation: `and` or `or`. - - `"web_search_preview_2025_03_11"` + - `"and"` - - `search_content_types: optional array of "text" or "image"` + - `"or"` - - `"text"` + - `max_num_results: optional number` - - `"image"` + The maximum number of results to return. This number should be between 1 and 50 inclusive. - - `search_context_size: optional "low" or "medium" or "high"` + - `ranking_options: optional object { hybrid_search, ranker, score_threshold }` - 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. + Ranking options for search. - - `"low"` + - `hybrid_search: optional object { embedding_weight, text_weight }` - - `"medium"` + Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. - - `"high"` + - `embedding_weight: number` - - `user_location: optional object { type, city, country, 2 more }` + The weight of the embedding in the reciprocal ranking fusion. - The user's location. + - `text_weight: number` - - `type: "approximate"` + The weight of the text in the reciprocal ranking fusion. - The type of location approximation. Always `approximate`. + - `ranker: optional "auto" or "default-2024-11-15"` - - `"approximate"` + The ranker to use for the file search. - - `city: optional string` + - `"auto"` - Free text input for the city of the user, e.g. `San Francisco`. + - `"default-2024-11-15"` - - `country: optional string` + - `score_threshold: optional number` - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + 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. - - `region: optional string` + - `Computer object { type }` - Free text input for the region of the user, e.g. `California`. + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `timezone: optional string` + - `type: "computer"` - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + The type of the computer tool. Always `computer`. - - `ApplyPatch object { type, allowed_callers }` + - `"computer"` - Allows the assistant to create, delete, or update files using unified diffs. + - `ComputerUsePreview object { display_height, display_width, environment, type }` - - `type: "apply_patch"` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - The type of the tool. Always `apply_patch`. + - `display_height: number` - - `"apply_patch"` + The height of the computer display. - - `allowed_callers: optional array of "direct" or "programmatic"` + - `display_width: number` - The tool invocation context(s). + The width of the computer display. - - `"direct"` + - `environment: "windows" or "mac" or "linux" or 2 more` - - `"programmatic"` + The type of computer environment to control. - - `top_p: number` + - `"windows"` - An alternative to sampling with temperature, called nucleus sampling, - where the model considers the results of the tokens with top_p probability - mass. So 0.1 means only the tokens comprising the top 10% probability mass - are considered. + - `"mac"` - We generally recommend altering this or `temperature` but not both. + - `"linux"` - - `background: optional boolean` + - `"ubuntu"` - Whether to run the model response in the background. - [Learn more](/docs/guides/background). + - `"browser"` - - `completed_at: optional number` + - `type: "computer_use_preview"` - Unix timestamp (in seconds) of when this Response was completed. - Only present when the status is `completed`. + The type of the computer use tool. Always `computer_use_preview`. - - `conversation: optional object { id }` + - `"computer_use_preview"` - The conversation that this response belonged to. Input items and output items from this response were automatically added to this conversation. + - `WebSearch object { type, filters, search_context_size, user_location }` - - `id: string` + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](/docs/guides/tools-web-search). - The unique ID of the conversation that this response was associated with. + - `type: "web_search" or "web_search_2025_08_26"` - - `max_output_tokens: optional number` + The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. - An upper bound for the number of tokens that can be generated for a response, including visible output tokens and [reasoning tokens](/docs/guides/reasoning). + - `"web_search"` - - `max_tool_calls: optional number` + - `"web_search_2025_08_26"` - The maximum number of total calls to built-in tools that can be processed in a response. This maximum number applies across all built-in tool calls, not per individual tool. Any further attempts to call a tool by the model will be ignored. + - `filters: optional object { allowed_domains }` - - `moderation: optional object { input, output }` + Filters for the search. - Moderation results for the response input and output, if moderated completions were requested. + - `allowed_domains: optional array of string` - - `input: object { categories, category_applied_input_types, category_scores, 3 more } or object { code, message, type }` + Allowed domains for the search. If not provided, all domains are allowed. + Subdomains of the provided domains are allowed as well. - Moderation for the response input. + Example: `["pubmed.ncbi.nlm.nih.gov"]` - - `ModerationResult object { categories, category_applied_input_types, category_scores, 3 more }` + - `search_context_size: optional "low" or "medium" or "high"` - A moderation result produced for the response input or output. + 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. - - `categories: map[boolean]` + - `"low"` - A dictionary of moderation categories to booleans, True if the input is flagged under this category. + - `"medium"` - - `category_applied_input_types: map[array of "text" or "image"]` + - `"high"` - Which modalities of input are reflected by the score for each category. + - `user_location: optional object { city, country, region, 2 more }` - - `"text"` + The approximate location of the user. - - `"image"` + - `city: optional string` - - `category_scores: map[number]` + Free text input for the city of the user, e.g. `San Francisco`. - A dictionary of moderation categories to scores. + - `country: optional string` - - `flagged: boolean` + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - A boolean indicating whether the content was flagged by any category. + - `region: optional string` - - `model: string` + Free text input for the region of the user, e.g. `California`. - The moderation model that produced this result. + - `timezone: optional string` - - `type: "moderation_result"` + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - The object type, which was always `moderation_result` for successful moderation results. + - `type: optional "approximate"` - - `"moderation_result"` + The type of location approximation. Always `approximate`. - - `Error object { code, message, type }` + - `"approximate"` - An error produced while attempting moderation for the response input or output. + - `Mcp object { server_label, type, allowed_callers, 9 more }` - - `code: 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 error code. + - `server_label: string` - - `message: string` + A label for this MCP server, used to identify it in tool calls. - The error message. + - `type: "mcp"` - - `type: "error"` + The type of the MCP tool. Always `mcp`. - The object type, which was always `error` for moderation failures. + - `"mcp"` - - `"error"` + - `allowed_callers: optional array of "direct" or "programmatic"` - - `output: object { categories, category_applied_input_types, category_scores, 3 more } or object { code, message, type }` + The tool invocation context(s). - Moderation for the response output. + - `"direct"` - - `ModerationResult object { categories, category_applied_input_types, category_scores, 3 more }` + - `"programmatic"` - A moderation result produced for the response input or output. + - `allowed_tools: optional array of string or object { read_only, tool_names }` - - `categories: map[boolean]` + List of allowed tool names or a filter object. - A dictionary of moderation categories to booleans, True if the input is flagged under this category. + - `McpAllowedTools = array of string` - - `category_applied_input_types: map[array of "text" or "image"]` + A string array of allowed tool names - Which modalities of input are reflected by the score for each category. + - `McpToolFilter object { read_only, tool_names }` - - `"text"` + A filter object to specify which tools are allowed. - - `"image"` + - `read_only: optional boolean` - - `category_scores: map[number]` + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. - A dictionary of moderation categories to scores. + - `tool_names: optional array of string` - - `flagged: boolean` + List of allowed tool names. - A boolean indicating whether the content was flagged by any category. + - `authorization: optional string` - - `model: 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 moderation model that produced this result. + - `connector_id: optional "connector_dropbox" or "connector_gmail" or "connector_googlecalendar" or 5 more` - - `type: "moderation_result"` + Identifier for service connectors, like those available in ChatGPT. One of + `server_url`, `connector_id`, or `tunnel_id` must be provided. Learn more + about service connectors [here](/docs/guides/tools-remote-mcp#connectors). - The object type, which was always `moderation_result` for successful moderation results. + Currently supported `connector_id` values are: - - `"moderation_result"` + - 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` - - `Error object { code, message, type }` + - `"connector_dropbox"` - An error produced while attempting moderation for the response input or output. + - `"connector_gmail"` - - `code: string` + - `"connector_googlecalendar"` - The error code. + - `"connector_googledrive"` - - `message: string` + - `"connector_microsoftteams"` - The error message. + - `"connector_outlookcalendar"` - - `type: "error"` + - `"connector_outlookemail"` - The object type, which was always `error` for moderation failures. + - `"connector_sharepoint"` - - `"error"` + - `defer_loading: optional boolean` - - `output_text: optional string` + Whether this MCP tool is deferred and discovered via tool search. - SDK-only convenience property that contains the aggregated text output - from all `output_text` items in the `output` array, if any are present. - Supported in the Python and JavaScript SDKs. + - `headers: optional map[string]` - - `previous_response_id: optional string` + Optional HTTP headers to send to the MCP server. Use for authentication + or other purposes. - The unique ID of the previous response to the model. Use this to - create multi-turn conversations. Learn more about - [conversation state](/docs/guides/conversation-state). Cannot be used in conjunction with `conversation`. + - `require_approval: optional object { always, never } or "always" or "never"` - - `prompt: optional ResponsePrompt` + Specify which of the MCP server's tools require approval. - Reference to a prompt template and its variables. - [Learn more](/docs/guides/text?api-mode=responses#reusable-prompts). + - `McpToolApprovalFilter object { always, never }` - - `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 identifier of the prompt template to use. + - `always: optional object { read_only, tool_names }` - - `variables: optional map[string or ResponseInputText or ResponseInputImage or ResponseInputFile]` + A filter object to specify which tools are allowed. - Optional map of values to substitute in for variables in your - prompt. The substitution values can either be strings, or other - Response input types like images or files. + - `read_only: optional boolean` - - `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. - - `ResponseInputText object { text, type, prompt_cache_breakpoint }` + - `tool_names: optional array of string` - A text input to the model. + List of allowed tool names. - - `ResponseInputImage object { detail, type, file_id, 2 more }` + - `never: optional object { read_only, tool_names }` - An image input to the model. Learn about [image inputs](/docs/guides/vision). + A filter object to specify which tools are allowed. - - `ResponseInputFile object { type, detail, file_data, 4 more }` + - `read_only: optional boolean` - A file 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. - - `version: optional string` + - `tool_names: optional array of string` - Optional version of the prompt template. + List of allowed tool names. - - `prompt_cache_key: optional string` + - `McpToolApprovalSetting = "always" or "never"` - Used by OpenAI to cache responses for similar requests to optimize your cache hit rates. Replaces the `user` field. [Learn more](/docs/guides/prompt-caching). + 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. - - `prompt_cache_options: optional object { mode, ttl }` + - `"always"` - The prompt-caching options that were applied to the response. Supported for `gpt-5.6` and later models. + - `"never"` - - `mode: "implicit" or "explicit"` + - `server_description: optional string` - Whether implicit prompt-cache breakpoints were enabled. + Optional description of the MCP server, used to provide more context. - - `"implicit"` + - `server_url: optional string` - - `"explicit"` + The URL for the MCP server. One of `server_url`, `connector_id`, or + `tunnel_id` must be provided. - - `ttl: "30m"` + - `tunnel_id: optional string` - The minimum lifetime applied to each cache breakpoint. + The Secure MCP Tunnel ID to use instead of a direct server URL. One of + `server_url`, `connector_id`, or `tunnel_id` must be provided. - - `"30m"` + - `CodeInterpreter object { container, type, allowed_callers }` - - `prompt_cache_retention: optional "in_memory" or "24h"` + A tool that runs Python code to help generate a response to a prompt. - Deprecated. Use `prompt_cache_options.ttl` instead. + - `container: string or object { type, file_ids, memory_limit, network_policy }` - The retention policy for the prompt cache. Set to `24h` to enable extended prompt caching, which keeps cached prefixes active for longer, up to a maximum of 24 hours. [Learn more](/docs/guides/prompt-caching#prompt-cache-retention). - This field expresses a maximum retention policy, while - `prompt_cache_options.ttl` expresses a minimum cache lifetime. The two - fields are independent and do not interact. - For `gpt-5.5`, `gpt-5.5-pro`, and future models, only `24h` is supported. + 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. - For older models that support both `in_memory` and `24h`, the default depends on your organization's data retention policy: + - `string` - - Organizations without ZDR enabled default to `24h`. - - Organizations with ZDR enabled default to `in_memory` when `prompt_cache_retention` is not specified. + The container ID. - - `"in_memory"` + - `CodeInterpreterToolAuto object { type, file_ids, memory_limit, network_policy }` - - `"24h"` + Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. - - `reasoning: optional Reasoning` + - `type: "auto"` - **gpt-5 and o-series models only** + Always `auto`. - Configuration options for - [reasoning models](https://platform.openai.com/docs/guides/reasoning). + - `"auto"` - - `context: optional "auto" or "current_turn" or "all_turns"` + - `file_ids: optional array of string` - Controls which reasoning items are rendered back to the model on later turns. - If omitted or set to `auto`, the model determines the context mode. The - `gpt-5.6` model family defaults to `all_turns`; earlier models default to - `current_turn`. + An optional list of uploaded files to make available to your code. - When returned on a response, this is the effective reasoning context mode - used for the response. + - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` - - `"auto"` + The memory limit for the code interpreter container. - - `"current_turn"` + - `"1g"` - - `"all_turns"` + - `"4g"` - - `effort: optional ReasoningEffort` + - `"16g"` - Constrains effort on reasoning for reasoning models. Currently supported - values are `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max`. - Reducing reasoning effort can result in faster responses and fewer tokens - used on reasoning in a response. Not all reasoning models support every - value. See the - [reasoning guide](https://platform.openai.com/docs/guides/reasoning) - for model-specific support. + - `"64g"` - - `"none"` + - `network_policy: optional ContainerNetworkPolicyDisabled or ContainerNetworkPolicyAllowlist` - - `"minimal"` + Network access policy for the container. - - `"low"` + - `ContainerNetworkPolicyDisabled object { type }` - - `"medium"` + - `type: "disabled"` - - `"high"` + Disable outbound network access. Always `disabled`. - - `"xhigh"` + - `"disabled"` - - `"max"` + - `ContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` - - `generate_summary: optional "auto" or "concise" or "detailed"` + - `allowed_domains: array of string` - **Deprecated:** use `summary` instead. + A list of allowed domains when type is `allowlist`. - A summary of the reasoning performed by the model. This can be - useful for debugging and understanding the model's reasoning process. - One of `auto`, `concise`, or `detailed`. + - `type: "allowlist"` - - `"auto"` + Allow outbound network access only to specified domains. Always `allowlist`. - - `"concise"` + - `"allowlist"` - - `"detailed"` + - `domain_secrets: optional array of ContainerNetworkPolicyDomainSecret` - - `mode: optional string or "standard" or "pro"` + Optional domain-scoped secrets for allowlisted domains. - Controls the reasoning execution mode for the request. + - `domain: string` - When returned on a response, this is the effective execution mode. + The domain associated with the secret. - - `string` + - `name: string` - - `"standard" or "pro"` + The name of the secret to inject for the domain. - Controls the reasoning execution mode for the request. + - `value: string` - When returned on a response, this is the effective execution mode. + The secret value to inject for the domain. - - `"standard"` + - `type: "code_interpreter"` - - `"pro"` + The type of the code interpreter tool. Always `code_interpreter`. - - `summary: optional "auto" or "concise" or "detailed"` + - `"code_interpreter"` - A summary of the reasoning performed by the model. This can be - useful for debugging and understanding the model's reasoning process. - One of `auto`, `concise`, or `detailed`. + - `allowed_callers: optional array of "direct" or "programmatic"` - `concise` is supported for `computer-use-preview` models and all reasoning models after `gpt-5`. + The tool invocation context(s). - - `"auto"` + - `"direct"` - - `"concise"` + - `"programmatic"` - - `"detailed"` + - `ProgrammaticToolCalling object { type }` - - `safety_identifier: optional string` + - `type: "programmatic_tool_calling"` - A stable identifier used to help detect users of your application that may be violating OpenAI's usage policies. - The IDs should be a string that uniquely identifies each user, with a maximum length of 64 characters. We recommend hashing their username or email address, in order to avoid sending us any identifying information. [Learn more](/docs/guides/safety-best-practices#safety-identifiers). + The type of the tool. Always `programmatic_tool_calling`. - - `service_tier: optional "auto" or "default" or "flex" or 2 more` + - `"programmatic_tool_calling"` - Specifies the processing type used for serving the request. + - `ImageGeneration object { type, action, background, 9 more }` - - If set to 'auto', then the request will be processed with the service tier configured in the Project settings. Unless otherwise configured, the Project will use 'default'. - - If set to 'default', then the request will be processed with the standard pricing and performance for the selected model. - - If set to '[flex](/docs/guides/flex-processing)' or '[priority](https://openai.com/api-priority-processing/)', then the request will be processed with the corresponding service tier. - - When not set, the default behavior is 'auto'. + A tool that generates images using the GPT image models. - When the `service_tier` parameter is set, the response body will include the `service_tier` value based on the processing mode actually used to serve the request. This response value may be different from the value set in the parameter. + - `type: "image_generation"` - - `"auto"` + The type of the image generation tool. Always `image_generation`. - - `"default"` + - `"image_generation"` - - `"flex"` + - `action: optional "generate" or "edit" or "auto"` - - `"scale"` + Whether to generate a new image or edit an existing image. Default: `auto`. - - `"priority"` + - `"generate"` - - `status: optional ResponseStatus` + - `"edit"` - The status of the response generation. One of `completed`, `failed`, - `in_progress`, `cancelled`, `queued`, or `incomplete`. + - `"auto"` - - `"completed"` + - `background: optional "transparent" or "opaque" or "auto"` - - `"failed"` + Background type for the generated image. One of `transparent`, + `opaque`, or `auto`. Default: `auto`. - - `"in_progress"` + - `"transparent"` - - `"cancelled"` + - `"opaque"` - - `"queued"` + - `"auto"` - - `"incomplete"` + - `input_fidelity: optional "high" or "low"` - - `text: optional ResponseTextConfig` + 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`. - Configuration options for a text response from the model. Can be plain - text or structured JSON data. Learn more: + - `"high"` - - [Text inputs and outputs](/docs/guides/text) - - [Structured Outputs](/docs/guides/structured-outputs) + - `"low"` - - `format: optional ResponseFormatTextConfig` + - `input_image_mask: optional object { file_id, image_url }` - An object specifying the format that the model must output. + Optional mask for inpainting. Contains `image_url` + (string, optional) and `file_id` (string, optional). - Configuring `{ "type": "json_schema" }` enables Structured Outputs, - which ensures the model will match your supplied JSON schema. Learn more in the - [Structured Outputs guide](/docs/guides/structured-outputs). + - `file_id: optional string` - The default format is `{ "type": "text" }` with no additional options. + File ID for the mask image. - **Not recommended for gpt-4o and newer models:** + - `image_url: optional string` - Setting to `{ "type": "json_object" }` enables the older JSON mode, which - ensures the message the model generates is valid JSON. Using `json_schema` - is preferred for models that support it. + Base64-encoded mask image. - - `ResponseFormatText object { type }` + - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` - Default response format. Used to generate text responses. + The image generation model to use. Default: `gpt-image-1`. - - `type: "text"` + - `string` - The type of response format being defined. Always `text`. + - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` - - `"text"` + The image generation model to use. Default: `gpt-image-1`. - - `ResponseFormatTextJSONSchemaConfig object { name, schema, type, 2 more }` + - `"gpt-image-1"` - JSON Schema response format. Used to generate structured JSON responses. - Learn more about [Structured Outputs](/docs/guides/structured-outputs). + - `"gpt-image-1-mini"` - - `name: string` - - The name of the response format. Must be a-z, A-Z, 0-9, or contain - underscores and dashes, with a maximum length of 64. - - - `schema: map[unknown]` + - `"gpt-image-1.5"` - The schema for the response format, described as a JSON Schema object. - Learn how to build JSON schemas [here](https://json-schema.org/). + - `moderation: optional "auto" or "low"` - - `type: "json_schema"` + Moderation level for the generated image. Default: `auto`. - The type of response format being defined. Always `json_schema`. + - `"auto"` - - `"json_schema"` + - `"low"` - - `description: optional string` + - `output_compression: optional number` - A description of what the response format is for, used by the model to - determine how to respond in the format. + Compression level for the output image. Default: 100. - - `strict: optional boolean` + - `output_format: optional "png" or "webp" or "jpeg"` - Whether to enable strict schema adherence when generating the output. - If set to true, the model will always follow the exact schema defined - in the `schema` field. Only a subset of JSON Schema is supported when - `strict` is `true`. To learn more, read the [Structured Outputs - guide](/docs/guides/structured-outputs). + The output format of the generated image. One of `png`, `webp`, or + `jpeg`. Default: `png`. - - `ResponseFormatJSONObject object { type }` + - `"png"` - JSON object response format. An older method of generating JSON responses. - Using `json_schema` is recommended for models that support it. Note that the - model will not generate JSON without a system or user message instructing it - to do so. + - `"webp"` - - `type: "json_object"` + - `"jpeg"` - The type of response format being defined. Always `json_object`. + - `partial_images: optional number` - - `"json_object"` + Number of partial images to generate in streaming mode, from 0 (default value) to 3. - - `verbosity: optional "low" or "medium" or "high"` + - `quality: optional "low" or "medium" or "high" or "auto"` - Constrains the verbosity of the model's response. Lower values will result in - more concise responses, while higher values will result in more verbose responses. - Currently supported values are `low`, `medium`, and `high`. The default is - `medium`. + The quality of the generated image. One of `low`, `medium`, `high`, + or `auto`. Default: `auto`. - `"low"` @@ -14688,2257 +14788,1319 @@ as input for the model's response. - `"high"` - - `top_logprobs: optional number` + - `"auto"` - An integer between 0 and 20 specifying the maximum number of most likely - tokens to return at each token position, each with an associated log - probability. In some cases, the number of returned tokens may be fewer than - requested. + - `size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or "auto"` - - `truncation: optional "auto" or "disabled"` + 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 truncation strategy to use for the model response. + - `string` - - `auto`: If the input to this Response exceeds - the model's context window size, the model will truncate the - response to fit the context window by dropping items from the beginning of the conversation. - - `disabled` (default): If the input size will exceed the context window - size for a model, the request will fail with a 400 error. + - `"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"` - - `"disabled"` + - `LocalShell object { type }` - - `usage: optional ResponseUsage` + A tool that allows the model to execute shell commands in a local environment. - Represents token usage details including input tokens, output tokens, - a breakdown of output tokens, and the total tokens used. + - `type: "local_shell"` - - `input_tokens: number` + The type of the local shell tool. Always `local_shell`. - The number of input tokens. + - `"local_shell"` - - `input_tokens_details: object { cache_write_tokens, cached_tokens }` + - `Shell object { type, allowed_callers, environment }` - A detailed breakdown of the input tokens. + A tool that allows the model to execute shell commands. - - `cache_write_tokens: number` + - `type: "shell"` - The number of input tokens that were written to the cache. + The type of the shell tool. Always `shell`. - - `cached_tokens: number` + - `"shell"` - The number of tokens that were retrieved from the cache. - [More on prompt caching](/docs/guides/prompt-caching). + - `allowed_callers: optional array of "direct" or "programmatic"` - - `output_tokens: number` + The tool invocation context(s). - The number of output tokens. + - `"direct"` - - `output_tokens_details: object { reasoning_tokens }` + - `"programmatic"` - A detailed breakdown of the output tokens. + - `environment: optional ContainerAuto or LocalEnvironment or ContainerReference` - - `reasoning_tokens: number` + - `ContainerAuto object { type, file_ids, memory_limit, 2 more }` - The number of reasoning tokens. + - `type: "container_auto"` - - `total_tokens: number` + Automatically creates a container for this request - The total number of tokens used. + - `"container_auto"` - - `user: optional string` + - `file_ids: optional array of string` - This field is being replaced by `safety_identifier` and `prompt_cache_key`. Use `prompt_cache_key` instead to maintain caching optimizations. - A stable identifier for your end-users. - Used to boost cache hit rates by better bucketing similar requests and to help OpenAI detect and prevent abuse. [Learn more](/docs/guides/safety-best-practices#safety-identifiers). + An optional list of uploaded files to make available to your code. -### Example + - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` -```http -curl https://api.openai.com/v1/responses \ - -H 'Content-Type: application/json' \ - -H "Authorization: Bearer $OPENAI_API_KEY" \ - -d '{ - "model": "gpt-5.1", - "prompt_cache_key": "prompt-cache-key-1234", - "safety_identifier": "safety-identifier-1234", - "temperature": 1, - "top_p": 1, - "user": "user-1234" - }' -``` + The memory limit for the container. -#### Response + - `"1g"` -```json -{ - "id": "id", - "created_at": 0, - "error": { - "code": "server_error", - "message": "message" - }, - "incomplete_details": { - "reason": "max_output_tokens" - }, - "instructions": "string", - "metadata": { - "foo": "string" - }, - "model": "gpt-5.1", - "object": "response", - "output": [ - { - "id": "id", - "content": [ - { - "annotations": [ - { - "file_id": "file_id", - "filename": "filename", - "index": 0, - "type": "file_citation" - } - ], - "logprobs": [ - { - "token": "token", - "bytes": [ - 0 - ], - "logprob": 0, - "top_logprobs": [ - { - "token": "token", - "bytes": [ - 0 - ], - "logprob": 0 - } - ] - } - ], - "text": "text", - "type": "output_text" - } - ], - "role": "assistant", - "status": "in_progress", - "type": "message", - "phase": "commentary" - } - ], - "parallel_tool_calls": true, - "temperature": 1, - "tool_choice": "none", - "tools": [ - { - "name": "name", - "parameters": { - "foo": "bar" - }, - "strict": true, - "type": "function", - "allowed_callers": [ - "direct" - ], - "defer_loading": true, - "description": "description", - "output_schema": { - "foo": "bar" - } - } - ], - "top_p": 1, - "background": true, - "completed_at": 0, - "conversation": { - "id": "id" - }, - "max_output_tokens": 0, - "max_tool_calls": 0, - "moderation": { - "input": { - "categories": { - "foo": true - }, - "category_applied_input_types": { - "foo": [ - "text" - ] - }, - "category_scores": { - "foo": 0 - }, - "flagged": true, - "model": "model", - "type": "moderation_result" - }, - "output": { - "categories": { - "foo": true - }, - "category_applied_input_types": { - "foo": [ - "text" - ] - }, - "category_scores": { - "foo": 0 - }, - "flagged": true, - "model": "model", - "type": "moderation_result" - } - }, - "output_text": "output_text", - "previous_response_id": "previous_response_id", - "prompt": { - "id": "id", - "variables": { - "foo": "string" - }, - "version": "version" - }, - "prompt_cache_key": "prompt-cache-key-1234", - "prompt_cache_options": { - "mode": "implicit", - "ttl": "30m" - }, - "prompt_cache_retention": "in_memory", - "reasoning": { - "context": "auto", - "effort": "none", - "generate_summary": "auto", - "mode": "standard", - "summary": "auto" - }, - "safety_identifier": "safety-identifier-1234", - "service_tier": "auto", - "status": "completed", - "text": { - "format": { - "type": "text" - }, - "verbosity": "low" - }, - "top_logprobs": 0, - "truncation": "auto", - "usage": { - "input_tokens": 0, - "input_tokens_details": { - "cache_write_tokens": 0, - "cached_tokens": 0 - }, - "output_tokens": 0, - "output_tokens_details": { - "reasoning_tokens": 0 - }, - "total_tokens": 0 - }, - "user": "user-1234" -} -``` + - `"4g"` -### Text input + - `"16g"` -```http -curl https://api.openai.com/v1/responses \ - -H "Content-Type: application/json" \ - -H "Authorization: Bearer $OPENAI_API_KEY" \ - -d '{ - "model": "gpt-5.4", - "input": "Tell me a three sentence bedtime story about a unicorn." - }' -``` + - `"64g"` -#### Response + - `network_policy: optional ContainerNetworkPolicyDisabled or ContainerNetworkPolicyAllowlist` -```json -{ - "id": "resp_67ccd2bed1ec8190b14f964abc0542670bb6a6b452d3795b", - "object": "response", - "created_at": 1741476542, - "status": "completed", - "completed_at": 1741476543, - "error": null, - "incomplete_details": null, - "instructions": null, - "max_output_tokens": null, - "model": "gpt-5.4", - "output": [ - { - "type": "message", - "id": "msg_67ccd2bf17f0819081ff3bb2cf6508e60bb6a6b452d3795b", - "status": "completed", - "role": "assistant", - "content": [ - { - "type": "output_text", - "text": "In a peaceful grove beneath a silver moon, a unicorn named Lumina discovered a hidden pool that reflected the stars. As she dipped her horn into the water, the pool began to shimmer, revealing a pathway to a magical realm of endless night skies. Filled with wonder, Lumina whispered a wish for all who dream to find their own hidden magic, and as she glanced back, her hoofprints sparkled like stardust.", - "annotations": [] - } - ] - } - ], - "parallel_tool_calls": true, - "previous_response_id": null, - "reasoning": { - "effort": null, - "summary": null - }, - "store": true, - "temperature": 1.0, - "text": { - "format": { - "type": "text" - } - }, - "tool_choice": "auto", - "tools": [], - "top_p": 1.0, - "truncation": "disabled", - "usage": { - "input_tokens": 36, - "input_tokens_details": { - "cached_tokens": 0, - "cache_write_tokens": 0 - }, - "output_tokens": 87, - "output_tokens_details": { - "reasoning_tokens": 0 - }, - "total_tokens": 123 - }, - "user": null, - "metadata": {} -} -``` + Network access policy for the container. -### Image input + - `ContainerNetworkPolicyDisabled object { type }` -```http -curl https://api.openai.com/v1/responses \ - -H "Content-Type: application/json" \ - -H "Authorization: Bearer $OPENAI_API_KEY" \ - -d '{ - "model": "gpt-5.4", - "input": [ - { - "role": "user", - "content": [ - {"type": "input_text", "text": "what is in this image?"}, - { - "type": "input_image", - "image_url": "https://upload.wikimedia.org/wikipedia/commons/thumb/d/dd/Gfp-wisconsin-madison-the-nature-boardwalk.jpg/2560px-Gfp-wisconsin-madison-the-nature-boardwalk.jpg" - } - ] - } - ] - }' -``` + - `ContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` -#### Response + - `skills: optional array of SkillReference or InlineSkill` -```json -{ - "id": "resp_67ccd3a9da748190baa7f1570fe91ac604becb25c45c1d41", - "object": "response", - "created_at": 1741476777, - "status": "completed", - "completed_at": 1741476778, - "error": null, - "incomplete_details": null, - "instructions": null, - "max_output_tokens": null, - "model": "gpt-5.4", - "output": [ - { - "type": "message", - "id": "msg_67ccd3acc8d48190a77525dc6de64b4104becb25c45c1d41", - "status": "completed", - "role": "assistant", - "content": [ - { - "type": "output_text", - "text": "The image depicts a scenic landscape with a wooden boardwalk or pathway leading through lush, green grass under a blue sky with some clouds. The setting suggests a peaceful natural area, possibly a park or nature reserve. There are trees and shrubs in the background.", - "annotations": [] - } - ] - } - ], - "parallel_tool_calls": true, - "previous_response_id": null, - "reasoning": { - "effort": null, - "summary": null - }, - "store": true, - "temperature": 1.0, - "text": { - "format": { - "type": "text" - } - }, - "tool_choice": "auto", - "tools": [], - "top_p": 1.0, - "truncation": "disabled", - "usage": { - "input_tokens": 328, - "input_tokens_details": { - "cached_tokens": 0, - "cache_write_tokens": 0 - }, - "output_tokens": 52, - "output_tokens_details": { - "reasoning_tokens": 0 - }, - "total_tokens": 380 - }, - "user": null, - "metadata": {} -} -``` + An optional list of skills referenced by id or inline data. -### File input + - `SkillReference object { skill_id, type, version }` -```http -curl https://api.openai.com/v1/responses \ - -H "Content-Type: application/json" \ - -H "Authorization: Bearer $OPENAI_API_KEY" \ - -d '{ - "model": "gpt-5.4", - "input": [ - { - "role": "user", - "content": [ - {"type": "input_text", "text": "what is in this file?"}, - { - "type": "input_file", - "file_url": "https://www.berkshirehathaway.com/letters/2024ltr.pdf", - "detail": "auto" - } - ] - } - ] - }' -``` + - `skill_id: string` -#### Response + The ID of the referenced skill. -```json -{ - "id": "resp_686eef60237881a2bd1180bb8b13de430e34c516d176ff86", - "object": "response", - "created_at": 1752100704, - "status": "completed", - "completed_at": 1752100705, - "background": false, - "error": null, - "incomplete_details": null, - "instructions": null, - "max_output_tokens": null, - "max_tool_calls": null, - "model": "gpt-5.4", - "output": [ - { - "id": "msg_686eef60d3e081a29283bdcbc4322fd90e34c516d176ff86", - "type": "message", - "status": "completed", - "content": [ - { - "type": "output_text", - "annotations": [], - "logprobs": [], - "text": "The file seems to contain excerpts from a letter to the shareholders of Berkshire Hathaway Inc., likely written by Warren Buffett. It covers several topics:\n\n1. **Communication Philosophy**: Buffett emphasizes the importance of transparency and candidness in reporting mistakes and successes to shareholders.\n\n2. **Mistakes and Learnings**: The letter acknowledges past mistakes in business assessments and management hires, highlighting the importance of correcting errors promptly.\n\n3. **CEO Succession**: Mention of Greg Abel stepping in as the new CEO and continuing the tradition of honest communication.\n\n4. **Pete Liegl Story**: A detailed account of acquiring Forest River and the relationship with its founder, highlighting trust and effective business decisions.\n\n5. **2024 Performance**: Overview of business performance, particularly in insurance and investment activities, with a focus on GEICO's improvement.\n\n6. **Tax Contributions**: Discussion of significant tax payments to the U.S. Treasury, credited to shareholders' reinvestments.\n\n7. **Investment Strategy**: A breakdown of Berkshire\u2019s investments in both controlled subsidiaries and marketable equities, along with a focus on long-term holding strategies.\n\n8. **American Capitalism**: Reflections on America\u2019s economic development and Berkshire\u2019s role within it.\n\n9. **Property-Casualty Insurance**: Insights into the P/C insurance business model and its challenges and benefits.\n\n10. **Japanese Investments**: Information about Berkshire\u2019s investments in Japanese companies and future plans.\n\n11. **Annual Meeting**: Details about the upcoming annual gathering in Omaha, including schedule changes and new book releases.\n\n12. **Personal Anecdotes**: Light-hearted stories about family and interactions, conveying Buffett's personable approach.\n\n13. **Financial Performance Data**: Tables comparing Berkshire\u2019s annual performance to the S&P 500, showing impressive long-term gains.\n\nOverall, the letter reinforces Berkshire Hathaway's commitment to transparency, investment in both its businesses and the wider economy, and emphasizes strong leadership and prudent financial management." - } - ], - "role": "assistant" - } - ], - "parallel_tool_calls": true, - "previous_response_id": null, - "reasoning": { - "effort": null, - "summary": null - }, - "service_tier": "default", - "store": true, - "temperature": 1.0, - "text": { - "format": { - "type": "text" - } - }, - "tool_choice": "auto", - "tools": [], - "top_logprobs": 0, - "top_p": 1.0, - "truncation": "disabled", - "usage": { - "input_tokens": 8438, - "input_tokens_details": { - "cached_tokens": 0, - "cache_write_tokens": 0 - }, - "output_tokens": 398, - "output_tokens_details": { - "reasoning_tokens": 0 - }, - "total_tokens": 8836 - }, - "user": null, - "metadata": {} -} -``` + - `type: "skill_reference"` -### Web search + References a skill created with the /v1/skills endpoint. -```http -curl https://api.openai.com/v1/responses \ - -H "Content-Type: application/json" \ - -H "Authorization: Bearer $OPENAI_API_KEY" \ - -d '{ - "model": "gpt-5.4", - "tools": [{ "type": "web_search_preview" }], - "input": "What was a positive news story from today?" - }' -``` + - `"skill_reference"` -#### Response + - `version: optional string` -```json -{ - "id": "resp_67ccf18ef5fc8190b16dbee19bc54e5f087bb177ab789d5c", - "object": "response", - "created_at": 1741484430, - "status": "completed", - "completed_at": 1741484431, - "error": null, - "incomplete_details": null, - "instructions": null, - "max_output_tokens": null, - "model": "gpt-5.4", - "output": [ - { - "type": "web_search_call", - "id": "ws_67ccf18f64008190a39b619f4c8455ef087bb177ab789d5c", - "status": "completed" - }, - { - "type": "message", - "id": "msg_67ccf190ca3881909d433c50b1f6357e087bb177ab789d5c", - "status": "completed", - "role": "assistant", - "content": [ - { - "type": "output_text", - "text": "As of today, March 9, 2025, one notable positive news story...", - "annotations": [ - { - "type": "url_citation", - "start_index": 442, - "end_index": 557, - "url": "https://.../?utm_source=chatgpt.com", - "title": "..." - }, - { - "type": "url_citation", - "start_index": 962, - "end_index": 1077, - "url": "https://.../?utm_source=chatgpt.com", - "title": "..." - }, - { - "type": "url_citation", - "start_index": 1336, - "end_index": 1451, - "url": "https://.../?utm_source=chatgpt.com", - "title": "..." - } - ] - } - ] - } - ], - "parallel_tool_calls": true, - "previous_response_id": null, - "reasoning": { - "effort": null, - "summary": null - }, - "store": true, - "temperature": 1.0, - "text": { - "format": { - "type": "text" - } - }, - "tool_choice": "auto", - "tools": [ - { - "type": "web_search_preview", - "domains": [], - "search_context_size": "medium", - "user_location": { - "type": "approximate", - "city": null, - "country": "US", - "region": null, - "timezone": null - } - } - ], - "top_p": 1.0, - "truncation": "disabled", - "usage": { - "input_tokens": 328, - "input_tokens_details": { - "cached_tokens": 0, - "cache_write_tokens": 0 - }, - "output_tokens": 356, - "output_tokens_details": { - "reasoning_tokens": 0 - }, - "total_tokens": 684 - }, - "user": null, - "metadata": {} -} -``` + Optional skill version. Use a positive integer or 'latest'. Omit for default. -### File search + - `InlineSkill object { description, name, source, type }` -```http -curl https://api.openai.com/v1/responses \ - -H "Content-Type: application/json" \ - -H "Authorization: Bearer $OPENAI_API_KEY" \ - -d '{ - "model": "gpt-5.4", - "tools": [{ - "type": "file_search", - "vector_store_ids": ["vs_1234567890"], - "max_num_results": 20 - }], - "input": "What are the attributes of an ancient brown dragon?" - }' -``` + - `description: string` -#### Response + The description of the skill. -```json -{ - "id": "resp_67ccf4c55fc48190b71bd0463ad3306d09504fb6872380d7", - "object": "response", - "created_at": 1741485253, - "status": "completed", - "completed_at": 1741485254, - "error": null, - "incomplete_details": null, - "instructions": null, - "max_output_tokens": null, - "model": "gpt-5.4", - "output": [ - { - "type": "file_search_call", - "id": "fs_67ccf4c63cd08190887ef6464ba5681609504fb6872380d7", - "status": "completed", - "queries": [ - "attributes of an ancient brown dragon" - ], - "results": null - }, - { - "type": "message", - "id": "msg_67ccf4c93e5c81909d595b369351a9d309504fb6872380d7", - "status": "completed", - "role": "assistant", - "content": [ - { - "type": "output_text", - "text": "The attributes of an ancient brown dragon include...", - "annotations": [ - { - "type": "file_citation", - "index": 320, - "file_id": "file-4wDz5b167pAf72nx1h9eiN", - "filename": "dragons.pdf" - }, - { - "type": "file_citation", - "index": 576, - "file_id": "file-4wDz5b167pAf72nx1h9eiN", - "filename": "dragons.pdf" - }, - { - "type": "file_citation", - "index": 815, - "file_id": "file-4wDz5b167pAf72nx1h9eiN", - "filename": "dragons.pdf" - }, - { - "type": "file_citation", - "index": 815, - "file_id": "file-4wDz5b167pAf72nx1h9eiN", - "filename": "dragons.pdf" - }, - { - "type": "file_citation", - "index": 1030, - "file_id": "file-4wDz5b167pAf72nx1h9eiN", - "filename": "dragons.pdf" - }, - { - "type": "file_citation", - "index": 1030, - "file_id": "file-4wDz5b167pAf72nx1h9eiN", - "filename": "dragons.pdf" - }, - { - "type": "file_citation", - "index": 1156, - "file_id": "file-4wDz5b167pAf72nx1h9eiN", - "filename": "dragons.pdf" - }, - { - "type": "file_citation", - "index": 1225, - "file_id": "file-4wDz5b167pAf72nx1h9eiN", - "filename": "dragons.pdf" - } - ] - } - ] - } - ], - "parallel_tool_calls": true, - "previous_response_id": null, - "reasoning": { - "effort": null, - "summary": null - }, - "store": true, - "temperature": 1.0, - "text": { - "format": { - "type": "text" - } - }, - "tool_choice": "auto", - "tools": [ - { - "type": "file_search", - "filters": null, - "max_num_results": 20, - "ranking_options": { - "ranker": "auto", - "score_threshold": 0.0 - }, - "vector_store_ids": [ - "vs_1234567890" - ] - } - ], - "top_p": 1.0, - "truncation": "disabled", - "usage": { - "input_tokens": 18307, - "input_tokens_details": { - "cached_tokens": 0, - "cache_write_tokens": 0 - }, - "output_tokens": 348, - "output_tokens_details": { - "reasoning_tokens": 0 - }, - "total_tokens": 18655 - }, - "user": null, - "metadata": {} -} -``` + - `name: string` -### Streaming + The name of the skill. -```http -curl https://api.openai.com/v1/responses \ - -H "Content-Type: application/json" \ - -H "Authorization: Bearer $OPENAI_API_KEY" \ - -d '{ - "model": "gpt-5.4", - "instructions": "You are a helpful assistant.", - "input": "Hello!", - "stream": true - }' -``` + - `source: InlineSkillSource` -#### Response + Inline skill payload -```json -event: response.created -data: {"type":"response.created","response":{"id":"resp_67c9fdcecf488190bdd9a0409de3a1ec07b8b0ad4e5eb654","object":"response","created_at":1741290958,"status":"in_progress","error":null,"incomplete_details":null,"instructions":"You are a helpful assistant.","max_output_tokens":null,"model":"gpt-5.4","output":[],"parallel_tool_calls":true,"previous_response_id":null,"reasoning":{"effort":null,"summary":null},"store":true,"temperature":1.0,"text":{"format":{"type":"text"}},"tool_choice":"auto","tools":[],"top_p":1.0,"truncation":"disabled","usage":null,"user":null,"metadata":{}}} + - `data: string` -event: response.in_progress -data: {"type":"response.in_progress","response":{"id":"resp_67c9fdcecf488190bdd9a0409de3a1ec07b8b0ad4e5eb654","object":"response","created_at":1741290958,"status":"in_progress","error":null,"incomplete_details":null,"instructions":"You are a helpful assistant.","max_output_tokens":null,"model":"gpt-5.4","output":[],"parallel_tool_calls":true,"previous_response_id":null,"reasoning":{"effort":null,"summary":null},"store":true,"temperature":1.0,"text":{"format":{"type":"text"}},"tool_choice":"auto","tools":[],"top_p":1.0,"truncation":"disabled","usage":null,"user":null,"metadata":{}}} + Base64-encoded skill zip bundle. -event: response.output_item.added -data: {"type":"response.output_item.added","output_index":0,"item":{"id":"msg_67c9fdcf37fc8190ba82116e33fb28c507b8b0ad4e5eb654","type":"message","status":"in_progress","role":"assistant","content":[]}} + - `media_type: "application/zip"` -event: response.content_part.added -data: {"type":"response.content_part.added","item_id":"msg_67c9fdcf37fc8190ba82116e33fb28c507b8b0ad4e5eb654","output_index":0,"content_index":0,"part":{"type":"output_text","text":"","annotations":[]}} + The media type of the inline skill payload. Must be `application/zip`. -event: response.output_text.delta -data: {"type":"response.output_text.delta","item_id":"msg_67c9fdcf37fc8190ba82116e33fb28c507b8b0ad4e5eb654","output_index":0,"content_index":0,"delta":"Hi"} + - `"application/zip"` -... + - `type: "base64"` -event: response.output_text.done -data: {"type":"response.output_text.done","item_id":"msg_67c9fdcf37fc8190ba82116e33fb28c507b8b0ad4e5eb654","output_index":0,"content_index":0,"text":"Hi there! How can I assist you today?"} + The type of the inline skill source. Must be `base64`. -event: response.content_part.done -data: {"type":"response.content_part.done","item_id":"msg_67c9fdcf37fc8190ba82116e33fb28c507b8b0ad4e5eb654","output_index":0,"content_index":0,"part":{"type":"output_text","text":"Hi there! How can I assist you today?","annotations":[]}} + - `"base64"` -event: response.output_item.done -data: {"type":"response.output_item.done","output_index":0,"item":{"id":"msg_67c9fdcf37fc8190ba82116e33fb28c507b8b0ad4e5eb654","type":"message","status":"completed","role":"assistant","content":[{"type":"output_text","text":"Hi there! How can I assist you today?","annotations":[]}]}} + - `type: "inline"` -event: response.completed -data: {"type":"response.completed","response":{"id":"resp_67c9fdcecf488190bdd9a0409de3a1ec07b8b0ad4e5eb654","object":"response","created_at":1741290958,"status":"completed","error":null,"incomplete_details":null,"instructions":"You are a helpful assistant.","max_output_tokens":null,"model":"gpt-5.4","output":[{"id":"msg_67c9fdcf37fc8190ba82116e33fb28c507b8b0ad4e5eb654","type":"message","status":"completed","role":"assistant","content":[{"type":"output_text","text":"Hi there! How can I assist you today?","annotations":[]}]}],"parallel_tool_calls":true,"previous_response_id":null,"reasoning":{"effort":null,"summary":null},"store":true,"temperature":1.0,"text":{"format":{"type":"text"}},"tool_choice":"auto","tools":[],"top_p":1.0,"truncation":"disabled","usage":{"input_tokens":37,"output_tokens":11,"output_tokens_details":{"reasoning_tokens":0},"total_tokens":48},"user":null,"metadata":{}}} -``` + Defines an inline skill for this request. -### Functions + - `"inline"` -```http -curl https://api.openai.com/v1/responses \ - -H "Content-Type: application/json" \ - -H "Authorization: Bearer $OPENAI_API_KEY" \ - -d '{ - "model": "gpt-5.4", - "input": "What is the weather like in Boston today?", - "tools": [ - { - "type": "function", - "name": "get_current_weather", - "description": "Get the current weather in a given location", - "parameters": { - "type": "object", - "properties": { - "location": { - "type": "string", - "description": "The city and state, e.g. San Francisco, CA" - }, - "unit": { - "type": "string", - "enum": ["celsius", "fahrenheit"] - } - }, - "required": ["location", "unit"] - } - } - ], - "tool_choice": "auto" - }' -``` + - `LocalEnvironment object { type, skills }` -#### Response + - `type: "local"` -```json -{ - "id": "resp_67ca09c5efe0819096d0511c92b8c890096610f474011cc0", - "object": "response", - "created_at": 1741294021, - "status": "completed", - "completed_at": 1741294022, - "error": null, - "incomplete_details": null, - "instructions": null, - "max_output_tokens": null, - "model": "gpt-5.4", - "output": [ - { - "type": "function_call", - "id": "fc_67ca09c6bedc8190a7abfec07b1a1332096610f474011cc0", - "call_id": "call_unLAR8MvFNptuiZK6K6HCy5k", - "name": "get_current_weather", - "arguments": "{\"location\":\"Boston, MA\",\"unit\":\"celsius\"}", - "status": "completed" - } - ], - "parallel_tool_calls": true, - "previous_response_id": null, - "reasoning": { - "effort": null, - "summary": null - }, - "store": true, - "temperature": 1.0, - "text": { - "format": { - "type": "text" - } - }, - "tool_choice": "auto", - "tools": [ - { - "type": "function", - "description": "Get the current weather in a given location", - "name": "get_current_weather", - "parameters": { - "type": "object", - "properties": { - "location": { - "type": "string", - "description": "The city and state, e.g. San Francisco, CA" - }, - "unit": { - "type": "string", - "enum": [ - "celsius", - "fahrenheit" - ] - } - }, - "required": [ - "location", - "unit" - ] - }, - "strict": true - } - ], - "top_p": 1.0, - "truncation": "disabled", - "usage": { - "input_tokens": 291, - "output_tokens": 23, - "output_tokens_details": { - "reasoning_tokens": 0 - }, - "total_tokens": 314 - }, - "user": null, - "metadata": {} -} -``` + Use a local computer environment. -### Reasoning + - `"local"` -```http -curl https://api.openai.com/v1/responses \ - -H "Content-Type: application/json" \ - -H "Authorization: Bearer $OPENAI_API_KEY" \ - -d '{ - "model": "o3-mini", - "input": "How much wood would a woodchuck chuck?", - "reasoning": { - "effort": "high" - } - }' -``` + - `skills: optional array of LocalSkill` -#### Response + An optional list of skills. -```json -{ - "id": "resp_67ccd7eca01881908ff0b5146584e408072912b2993db808", - "object": "response", - "created_at": 1741477868, - "status": "completed", - "completed_at": 1741477869, - "error": null, - "incomplete_details": null, - "instructions": null, - "max_output_tokens": null, - "model": "o1-2024-12-17", - "output": [ - { - "type": "message", - "id": "msg_67ccd7f7b5848190a6f3e95d809f6b44072912b2993db808", - "status": "completed", - "role": "assistant", - "content": [ - { - "type": "output_text", - "text": "The classic tongue twister...", - "annotations": [] - } - ] - } - ], - "parallel_tool_calls": true, - "previous_response_id": null, - "reasoning": { - "effort": "high", - "summary": null - }, - "store": true, - "temperature": 1.0, - "text": { - "format": { - "type": "text" - } - }, - "tool_choice": "auto", - "tools": [], - "top_p": 1.0, - "truncation": "disabled", - "usage": { - "input_tokens": 81, - "input_tokens_details": { - "cached_tokens": 0, - "cache_write_tokens": 0 - }, - "output_tokens": 1035, - "output_tokens_details": { - "reasoning_tokens": 832 - }, - "total_tokens": 1116 - }, - "user": null, - "metadata": {} -} -``` - -## Get a model response - -**get** `/responses/{response_id}` - -Retrieves a model response with the given ID. - -### Path Parameters + - `description: string` -- `response_id: string` + The description of the skill. -### Query Parameters + - `name: string` -- `include: optional array of ResponseIncludable` + The name of the skill. - Additional fields to include in the response. See the `include` - parameter for Response creation above for more information. + - `path: string` - - `"file_search_call.results"` + The path to the directory containing the skill. - - `"web_search_call.results"` + - `ContainerReference object { container_id, type }` - - `"web_search_call.action.sources"` + - `container_id: string` - - `"message.input_image.image_url"` + The ID of the referenced container. - - `"computer_call_output.output.image_url"` + - `type: "container_reference"` - - `"code_interpreter_call.outputs"` + References a container created with the /v1/containers endpoint - - `"reasoning.encrypted_content"` + - `"container_reference"` - - `"message.output_text.logprobs"` + - `Custom object { name, type, allowed_callers, 3 more }` -- `include_obfuscation: optional boolean` + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) - When true, stream obfuscation will be enabled. Stream obfuscation adds - random characters to an `obfuscation` field on streaming delta events - to normalize payload sizes as a mitigation to certain side-channel - attacks. These obfuscation fields are included by default, but add a - small amount of overhead to the data stream. You can set - `include_obfuscation` to false to optimize for bandwidth if you trust - the network links between your application and the OpenAI API. + - `name: string` -- `starting_after: optional number` + The name of the custom tool, used to identify it in tool calls. - The sequence number of the event after which to start streaming. + - `type: "custom"` -- `stream: optional false` + The type of the custom tool. Always `custom`. - If set to true, the model response data will be streamed to the client - as it is generated using [server-sent events](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events/Using_server-sent_events#Event_stream_format). - See the [Streaming section below](/docs/api-reference/responses-streaming) - for more information. + - `"custom"` - - `false` + - `allowed_callers: optional array of "direct" or "programmatic"` -### Returns + The tool invocation context(s). -- `Response object { id, created_at, error, 32 more }` + - `"direct"` - - `id: string` + - `"programmatic"` - Unique identifier for this Response. + - `defer_loading: optional boolean` - - `created_at: number` + Whether this tool should be deferred and discovered via tool search. - Unix timestamp (in seconds) of when this Response was created. + - `description: optional string` - - `error: ResponseError` + Optional description of the custom tool, used to provide more context. - An error object returned when the model fails to generate a Response. + - `format: optional CustomToolInputFormat` - - `code: "server_error" or "rate_limit_exceeded" or "invalid_prompt" or 17 more` + The input format for the custom tool. Default is unconstrained text. - The error code for the response. + - `Text object { type }` - - `"server_error"` + Unconstrained free-form text. - - `"rate_limit_exceeded"` + - `type: "text"` - - `"invalid_prompt"` + Unconstrained text format. Always `text`. - - `"data_residency_mismatch"` + - `"text"` - - `"bio_policy"` + - `Grammar object { definition, syntax, type }` - - `"vector_store_timeout"` + A grammar defined by the user. - - `"invalid_image"` + - `definition: string` - - `"invalid_image_format"` + The grammar definition. - - `"invalid_base64_image"` + - `syntax: "lark" or "regex"` - - `"invalid_image_url"` + The syntax of the grammar definition. One of `lark` or `regex`. - - `"image_too_large"` + - `"lark"` - - `"image_too_small"` + - `"regex"` - - `"image_parse_error"` + - `type: "grammar"` - - `"image_content_policy_violation"` + Grammar format. Always `grammar`. - - `"invalid_image_mode"` + - `"grammar"` - - `"image_file_too_large"` + - `Namespace object { description, name, tools, type }` - - `"unsupported_image_media_type"` + Groups function/custom tools under a shared namespace. - - `"empty_image_file"` + - `description: string` - - `"failed_to_download_image"` + A description of the namespace shown to the model. - - `"image_file_not_found"` + - `name: string` - - `message: string` + The namespace name used in tool calls (for example, `crm`). - A human-readable description of the error. + - `tools: array of object { name, type, allowed_callers, 5 more } or object { name, type, allowed_callers, 3 more }` - - `incomplete_details: object { reason }` + The function/custom tools available inside this namespace. - Details about why the response is incomplete. + - `Function object { name, type, allowed_callers, 5 more }` - - `reason: optional "max_output_tokens" or "content_filter"` + - `name: string` - The reason why the response is incomplete. + - `type: "function"` - - `"max_output_tokens"` + - `"function"` - - `"content_filter"` + - `allowed_callers: optional array of "direct" or "programmatic"` - - `instructions: string or array of EasyInputMessage or object { content, role, status, type } or ResponseOutputMessage or 29 more` + The tool invocation context(s). - A system (or developer) message inserted into the model's context. + - `"direct"` - When using along with `previous_response_id`, the instructions from a previous - response will not be carried over to the next response. This makes it simple - to swap out system (or developer) messages in new responses. + - `"programmatic"` - - `string` + - `defer_loading: optional boolean` - A text input to the model, equivalent to a text input with the - `developer` role. + Whether this function should be deferred and discovered via tool search. - - `InputItemList = array of EasyInputMessage or object { content, role, status, type } or ResponseOutputMessage or 29 more` + - `description: optional string` - A list of one or many input items to the model, containing - different content types. + - `output_schema: optional map[unknown]` - - `EasyInputMessage object { content, role, phase, type }` + A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. - 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. + - `parameters: optional unknown` - - `content: string or ResponseInputMessageContentList` + - `strict: optional boolean` - Text, image, or audio input to the model, used to generate a response. - Can also contain previous assistant responses. + Whether to enforce strict parameter validation. If omitted, Responses attempts to use strict validation when the schema is compatible, and falls back to non-strict validation otherwise. - - `TextInput = string` + - `Custom object { name, type, allowed_callers, 3 more }` - A text input to the model. + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) - - `ResponseInputMessageContentList = array of ResponseInputContent` + - `name: string` - A list of one or many input items to the model, containing different content - types. + The name of the custom tool, used to identify it in tool calls. - - `ResponseInputText object { text, type, prompt_cache_breakpoint }` + - `type: "custom"` - A text input to the model. + The type of the custom tool. Always `custom`. - - `text: string` + - `"custom"` - The text input to the model. + - `allowed_callers: optional array of "direct" or "programmatic"` - - `type: "input_text"` + The tool invocation context(s). - The type of the input item. Always `input_text`. + - `"direct"` - - `"input_text"` + - `"programmatic"` - - `prompt_cache_breakpoint: optional object { mode }` + - `defer_loading: optional boolean` - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + Whether this tool should be deferred and discovered via tool search. - - `mode: "explicit"` + - `description: optional string` - The breakpoint mode. Always `explicit`. + Optional description of the custom tool, used to provide more context. - - `"explicit"` + - `format: optional CustomToolInputFormat` - - `ResponseInputImage object { detail, type, file_id, 2 more }` + The input format for the custom tool. Default is unconstrained text. - An image input to the model. Learn about [image inputs](/docs/guides/vision). + - `type: "namespace"` - - `detail: "low" or "high" or "auto" or "original"` + The type of the tool. Always `namespace`. - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + - `"namespace"` - - `"low"` + - `ToolSearch object { type, description, execution, parameters }` - - `"high"` + Hosted or BYOT tool search configuration for deferred tools. - - `"auto"` + - `type: "tool_search"` - - `"original"` + 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. - - `file_id: optional string` + - `execution: optional "server" or "client"` - The ID of the file to be sent to the model. + Whether tool search is executed by the server or by the client. - - `image_url: optional string` + - `"server"` - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + - `"client"` - - `prompt_cache_breakpoint: optional object { mode }` + - `parameters: optional unknown` - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + Parameter schema for a client-executed tool search tool. - - `mode: "explicit"` + - `WebSearchPreview object { type, search_content_types, search_context_size, user_location }` - The breakpoint mode. Always `explicit`. + 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). - - `"explicit"` + - `type: "web_search_preview" or "web_search_preview_2025_03_11"` - - `ResponseInputFile object { type, detail, file_data, 4 more }` + The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. - A file input to the model. + - `"web_search_preview"` - - `type: "input_file"` + - `"web_search_preview_2025_03_11"` - The type of the input item. Always `input_file`. + - `search_content_types: optional array of "text" or "image"` - - `"input_file"` + - `"text"` - - `detail: optional "auto" or "low" or "high"` + - `"image"` - The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. + - `search_context_size: optional "low" or "medium" or "high"` - - `"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"` - - `file_data: optional string` + - `user_location: optional object { type, city, country, 2 more }` - The content of the file to be sent to the model. + The user's location. - - `file_id: optional string` + - `type: "approximate"` - The ID of the file to be sent to the model. + The type of location approximation. Always `approximate`. - - `file_url: optional string` + - `"approximate"` - The URL of the file to be sent to the model. + - `city: optional string` - - `filename: optional string` + Free text input for the city of the user, e.g. `San Francisco`. - The name of the file to be sent to the model. + - `country: optional string` - - `prompt_cache_breakpoint: optional object { mode }` + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + - `region: optional string` - - `mode: "explicit"` + Free text input for the region of the user, e.g. `California`. - The breakpoint mode. Always `explicit`. + - `timezone: optional string` - - `"explicit"` + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - - `role: "user" or "assistant" or "system" or "developer"` + - `ApplyPatch object { type, allowed_callers }` - The role of the message input. One of `user`, `assistant`, `system`, or - `developer`. + 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"` - - `"developer"` + - `allowed_callers: optional array of "direct" or "programmatic"` - - `phase: optional "commentary" or "final_answer"` + The tool invocation context(s). - 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. + - `"direct"` - - `"commentary"` + - `"programmatic"` - - `"final_answer"` + - `type: "tool_search_output"` - - `type: optional "message"` + The type of the item. Always `tool_search_output`. - The type of the message input. Always `message`. + - `"tool_search_output"` - - `"message"` + - `created_by: optional string` - - `Message object { content, role, status, type }` + The identifier of the actor that created the item. - 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. + - `AdditionalTools object { id, role, tools, type }` - - `content: ResponseInputMessageContentList` + - `id: string` - A list of one or many input items to the model, containing different content - types. + The unique ID of the additional tools item. - - `role: "user" or "system" or "developer"` + - `role: "unknown" or "user" or "assistant" or 5 more` - The role of the message input. One of `user`, `system`, or `developer`. + The role that provided the additional tools. + + - `"unknown"` - `"user"` + - `"assistant"` + - `"system"` - - `"developer"` + - `"critic"` - - `status: optional "in_progress" or "completed" or "incomplete"` + - `"discriminator"` - The status of item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `"developer"` - - `"in_progress"` + - `"tool"` - - `"completed"` + - `tools: array of object { name, parameters, strict, 5 more } or object { type, vector_store_ids, filters, 2 more } or object { type } or 13 more` - - `"incomplete"` + The additional tool definitions made available at this item. - - `type: optional "message"` + - `Function object { name, parameters, strict, 5 more }` - The type of the message input. Always set to `message`. + 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). - - `"message"` + - `name: string` - - `ResponseOutputMessage object { id, content, role, 3 more }` + The name of the function to call. - An output message from the model. + - `parameters: map[unknown]` - - `id: string` + A JSON schema object describing the parameters of the function. - The unique ID of the output message. + - `strict: boolean` - - `content: array of ResponseOutputText or ResponseOutputRefusal` + Whether strict parameter validation is enforced for this function tool. - The content of the output message. + - `type: "function"` - - `ResponseOutputText object { annotations, logprobs, text, type }` + The type of the function tool. Always `function`. - A text output from the model. + - `"function"` - - `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 }` + - `allowed_callers: optional array of "direct" or "programmatic"` - The annotations of the text output. + The tool invocation context(s). - - `FileCitation object { file_id, filename, index, type }` + - `"direct"` - A citation to a file. + - `"programmatic"` - - `file_id: string` + - `defer_loading: optional boolean` - The ID of the file. + Whether this function is deferred and loaded via tool search. - - `filename: string` + - `description: optional string` - The filename of the file cited. + A description of the function. Used by the model to determine whether or not to call the function. - - `index: number` + - `output_schema: optional map[unknown]` - The index of the file in the list of files. + A JSON schema object describing the JSON value encoded in string outputs for this function. - - `type: "file_citation"` + - `FileSearch object { type, vector_store_ids, filters, 2 more }` - The type of the file citation. Always `file_citation`. + 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). - - `"file_citation"` + - `type: "file_search"` - - `URLCitation object { end_index, start_index, title, 2 more }` + The type of the file search tool. Always `file_search`. - A citation for a web resource used to generate a model response. + - `"file_search"` - - `end_index: number` + - `vector_store_ids: array of string` - The index of the last character of the URL citation in the message. + The IDs of the vector stores to search. - - `start_index: number` + - `filters: optional ComparisonFilter or CompoundFilter` - The index of the first character of the URL citation in the message. + A filter to apply. - - `title: string` + - `ComparisonFilter object { key, type, value }` - The title of the web resource. + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - - `type: "url_citation"` + - `CompoundFilter object { filters, type }` - The type of the URL citation. Always `url_citation`. + Combine multiple filters using `and` or `or`. - - `"url_citation"` + - `max_num_results: optional number` - - `url: string` + The maximum number of results to return. This number should be between 1 and 50 inclusive. - The URL of the web resource. + - `ranking_options: optional object { hybrid_search, ranker, score_threshold }` - - `ContainerFileCitation object { container_id, end_index, file_id, 3 more }` + Ranking options for search. - A citation for a container file used to generate a model response. + - `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. - The ID of the container file. + - `embedding_weight: number` - - `end_index: number` + The weight of the embedding in the reciprocal ranking fusion. - The index of the last character of the container file citation in the message. + - `text_weight: number` - - `file_id: string` + The weight of the text in the reciprocal ranking fusion. - The ID of the file. + - `ranker: optional "auto" or "default-2024-11-15"` - - `filename: string` + The ranker to use for the file search. - The filename of the container file cited. + - `"auto"` - - `start_index: number` + - `"default-2024-11-15"` - The index of the first character of the container file citation in the message. + - `score_threshold: optional number` - - `type: "container_file_citation"` + The score threshold for the file search, a number between 0 and 1. Numbers closer to 1 will attempt to return only the most relevant results, but may return fewer results. - The type of the container file citation. Always `container_file_citation`. + - `Computer object { type }` - - `"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). - - `FilePath object { file_id, index, type }` + - `type: "computer"` - A path to a file. + The type of the computer tool. Always `computer`. - - `file_id: string` + - `"computer"` - The ID of the file. + - `ComputerUsePreview object { display_height, display_width, environment, type }` - - `index: number` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - The index of the file in the list of files. + - `display_height: number` - - `type: "file_path"` + The height of the computer display. - The type of the file path. Always `file_path`. + - `display_width: number` - - `"file_path"` + The width of the computer display. - - `logprobs: array of object { token, bytes, logprob, top_logprobs }` + - `environment: "windows" or "mac" or "linux" or 2 more` - - `token: string` + The type of computer environment to control. - - `bytes: array of number` + - `"windows"` - - `logprob: number` + - `"mac"` - - `top_logprobs: array of object { token, bytes, logprob }` + - `"linux"` - - `token: string` + - `"ubuntu"` - - `bytes: array of number` + - `"browser"` - - `logprob: number` + - `type: "computer_use_preview"` - - `text: string` + The type of the computer use tool. Always `computer_use_preview`. - The text output from the model. + - `"computer_use_preview"` - - `type: "output_text"` + - `WebSearch object { type, filters, search_context_size, user_location }` - The type of the output text. Always `output_text`. + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](/docs/guides/tools-web-search). - - `"output_text"` + - `type: "web_search" or "web_search_2025_08_26"` - - `ResponseOutputRefusal object { refusal, type }` + The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. - A refusal from the model. + - `"web_search"` - - `refusal: string` + - `"web_search_2025_08_26"` - The refusal explanation from the model. + - `filters: optional object { allowed_domains }` - - `type: "refusal"` + Filters for the search. - The type of the refusal. Always `refusal`. + - `allowed_domains: optional array of string` - - `"refusal"` + Allowed domains for the search. If not provided, all domains are allowed. + Subdomains of the provided domains are allowed as well. - - `role: "assistant"` + Example: `["pubmed.ncbi.nlm.nih.gov"]` - The role of the output message. Always `assistant`. + - `search_context_size: optional "low" or "medium" or "high"` - - `"assistant"` + 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: "in_progress" or "completed" or "incomplete"` + - `"low"` - The status of the message input. One of `in_progress`, `completed`, or - `incomplete`. Populated when input items are returned via API. + - `"medium"` - - `"in_progress"` + - `"high"` - - `"completed"` + - `user_location: optional object { city, country, region, 2 more }` - - `"incomplete"` + The approximate location of the user. - - `type: "message"` + - `city: optional string` - The type of the output message. Always `message`. + Free text input for the city of the user, e.g. `San Francisco`. - - `"message"` + - `country: optional string` - - `phase: optional "commentary" or "final_answer"` + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - 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. + - `region: optional string` - - `"commentary"` + Free text input for the region of the user, e.g. `California`. - - `"final_answer"` + - `timezone: optional string` - - `FileSearchCall object { id, queries, status, 2 more }` + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - The results of a file search tool call. See the - [file search guide](/docs/guides/tools-file-search) for more information. + - `type: optional "approximate"` - - `id: string` + The type of location approximation. Always `approximate`. - The unique ID of the file search tool call. + - `"approximate"` - - `queries: array of string` + - `Mcp object { server_label, type, allowed_callers, 9 more }` - The queries used to search for files. + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](/docs/guides/tools-remote-mcp). - - `status: "in_progress" or "searching" or "completed" or 2 more` + - `server_label: string` - The status of the file search tool call. One of `in_progress`, - `searching`, `incomplete` or `failed`, + A label for this MCP server, used to identify it in tool calls. - - `"in_progress"` + - `type: "mcp"` - - `"searching"` + The type of the MCP tool. Always `mcp`. - - `"completed"` + - `"mcp"` - - `"incomplete"` + - `allowed_callers: optional array of "direct" or "programmatic"` - - `"failed"` + The tool invocation context(s). - - `type: "file_search_call"` + - `"direct"` - The type of the file search tool call. Always `file_search_call`. + - `"programmatic"` - - `"file_search_call"` + - `allowed_tools: optional array of string or object { read_only, tool_names }` - - `results: optional array of object { attributes, file_id, filename, 2 more }` + List of allowed tool names or a filter object. - The results of the file search tool call. + - `McpAllowedTools = array of string` - - `attributes: optional map[string or number or boolean]` + A string array of allowed tool names - 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. + - `McpToolFilter object { read_only, tool_names }` - - `string` + A filter object to specify which tools are allowed. - - `number` + - `read_only: optional boolean` - - `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. - - `file_id: optional string` + - `tool_names: optional array of string` - The unique ID of the file. + List of allowed tool names. - - `filename: optional string` + - `authorization: optional string` - The name of the file. + 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. - - `score: optional number` + - `connector_id: optional "connector_dropbox" or "connector_gmail" or "connector_googlecalendar" or 5 more` - The relevance score of the file - a value between 0 and 1. + Identifier for service connectors, like those available in ChatGPT. One of + `server_url`, `connector_id`, or `tunnel_id` must be provided. Learn more + about service connectors [here](/docs/guides/tools-remote-mcp#connectors). - - `text: optional string` + Currently supported `connector_id` values are: - The text that was retrieved from the file. + - 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` - - `ComputerCall object { id, call_id, pending_safety_checks, 4 more }` + - `"connector_dropbox"` - A tool call to a computer use tool. See the - [computer use guide](/docs/guides/tools-computer-use) for more information. + - `"connector_gmail"` - - `id: string` + - `"connector_googlecalendar"` - The unique ID of the computer call. + - `"connector_googledrive"` - - `call_id: string` + - `"connector_microsoftteams"` - An identifier used when responding to the tool call with output. + - `"connector_outlookcalendar"` - - `pending_safety_checks: array of object { id, code, message }` + - `"connector_outlookemail"` - The pending safety checks for the computer call. + - `"connector_sharepoint"` - - `id: string` + - `defer_loading: optional boolean` - The ID of the pending safety check. + Whether this MCP tool is deferred and discovered via tool search. - - `code: optional string` + - `headers: optional map[string]` - The type of the pending safety check. + Optional HTTP headers to send to the MCP server. Use for authentication + or other purposes. - - `message: optional string` + - `require_approval: optional object { always, never } or "always" or "never"` - Details about the pending safety check. + Specify which of the MCP server's tools require approval. - - `status: "in_progress" or "completed" or "incomplete"` + - `McpToolApprovalFilter object { always, never }` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are 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. - - `"in_progress"` + - `always: optional object { read_only, tool_names }` - - `"completed"` + A filter object to specify which tools are allowed. - - `"incomplete"` + - `read_only: optional boolean` - - `type: "computer_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 computer call. Always `computer_call`. + - `tool_names: optional array of string` - - `"computer_call"` + List of allowed tool names. - - `action: optional ComputerAction` + - `never: optional object { read_only, tool_names }` - A click action. + A filter object to specify which tools are allowed. - - `Click object { button, type, x, 2 more }` + - `read_only: optional boolean` - A click action. + 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. - - `button: "left" or "right" or "wheel" or 2 more` + - `tool_names: optional array of string` - Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. + List of allowed tool names. - - `"left"` + - `McpToolApprovalSetting = "always" or "never"` - - `"right"` + 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. - - `"wheel"` + - `"always"` - - `"back"` + - `"never"` - - `"forward"` + - `server_description: optional string` - - `type: "click"` + Optional description of the MCP server, used to provide more context. - Specifies the event type. For a click action, this property is always `click`. + - `server_url: optional string` - - `"click"` + The URL for the MCP server. One of `server_url`, `connector_id`, or + `tunnel_id` must be provided. - - `x: number` + - `tunnel_id: optional string` - The x-coordinate where the click occurred. + The Secure MCP Tunnel ID to use instead of a direct server URL. One of + `server_url`, `connector_id`, or `tunnel_id` must be provided. - - `y: number` + - `CodeInterpreter object { container, type, allowed_callers }` - The y-coordinate where the click occurred. + A tool that runs Python code to help generate a response to a prompt. - - `keys: optional array of string` + - `container: string or object { type, file_ids, memory_limit, network_policy }` - The keys being held while clicking. + 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. - - `DoubleClick object { keys, type, x, y }` + - `string` - A double click action. + The container ID. - - `keys: array of string` + - `CodeInterpreterToolAuto object { type, file_ids, memory_limit, network_policy }` - The keys being held while double-clicking. + Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. - - `type: "double_click"` + - `type: "auto"` - Specifies the event type. For a double click action, this property is always set to `double_click`. + Always `auto`. - - `"double_click"` + - `"auto"` - - `x: number` + - `file_ids: optional array of string` - The x-coordinate where the double click occurred. + An optional list of uploaded files to make available to your code. - - `y: number` + - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` - The y-coordinate where the double click occurred. + The memory limit for the code interpreter container. - - `Drag object { path, type, keys }` + - `"1g"` - A drag action. + - `"4g"` - - `path: array of object { x, y }` + - `"16g"` - An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg + - `"64g"` - ``` - [ - { x: 100, y: 200 }, - { x: 200, y: 300 } - ] - ``` + - `network_policy: optional ContainerNetworkPolicyDisabled or ContainerNetworkPolicyAllowlist` - - `x: number` + Network access policy for the container. - The x-coordinate. + - `ContainerNetworkPolicyDisabled object { type }` - - `y: number` + - `ContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` - The y-coordinate. + - `type: "code_interpreter"` - - `type: "drag"` + The type of the code interpreter tool. Always `code_interpreter`. - Specifies the event type. For a drag action, this property is always set to `drag`. + - `"code_interpreter"` - - `"drag"` + - `allowed_callers: optional array of "direct" or "programmatic"` - - `keys: optional array of string` + The tool invocation context(s). - The keys being held while dragging the mouse. + - `"direct"` - - `Keypress object { keys, type }` + - `"programmatic"` - A collection of keypresses the model would like to perform. + - `ProgrammaticToolCalling object { type }` - - `keys: array of string` + - `type: "programmatic_tool_calling"` - 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 tool. Always `programmatic_tool_calling`. - - `type: "keypress"` + - `"programmatic_tool_calling"` - Specifies the event type. For a keypress action, this property is always set to `keypress`. + - `ImageGeneration object { type, action, background, 9 more }` - - `"keypress"` + A tool that generates images using the GPT image models. - - `Move object { type, x, y, keys }` + - `type: "image_generation"` - A mouse move action. + The type of the image generation tool. Always `image_generation`. - - `type: "move"` + - `"image_generation"` - Specifies the event type. For a move action, this property is always set to `move`. + - `action: optional "generate" or "edit" or "auto"` - - `"move"` + Whether to generate a new image or edit an existing image. Default: `auto`. - - `x: number` + - `"generate"` - The x-coordinate to move to. + - `"edit"` - - `y: number` + - `"auto"` - The y-coordinate to move to. + - `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 moving the mouse. + - `"transparent"` - - `Screenshot object { type }` + - `"opaque"` - A screenshot action. + - `"auto"` - - `type: "screenshot"` + - `input_fidelity: optional "high" or "low"` - Specifies the event type. For a screenshot action, this property is always set to `screenshot`. + 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`. - - `"screenshot"` + - `"high"` - - `Scroll object { scroll_x, scroll_y, type, 3 more }` + - `"low"` - A scroll action. + - `input_image_mask: optional object { file_id, image_url }` - - `scroll_x: number` + Optional mask for inpainting. Contains `image_url` + (string, optional) and `file_id` (string, optional). - The horizontal scroll distance. + - `file_id: optional string` - - `scroll_y: number` + File ID for the mask image. - The vertical scroll distance. + - `image_url: optional string` - - `type: "scroll"` + Base64-encoded mask image. - Specifies the event type. For a scroll action, this property is always set to `scroll`. + - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` - - `"scroll"` + The image generation model to use. Default: `gpt-image-1`. - - `x: number` + - `string` - The x-coordinate where the scroll occurred. + - `"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 scroll occurred. + - `"gpt-image-1"` - - `keys: optional array of string` + - `"gpt-image-1-mini"` - The keys being held while scrolling. + - `"gpt-image-1.5"` - - `Type object { text, type }` + - `moderation: optional "auto" or "low"` - An action to type in text. + Moderation level for the generated image. Default: `auto`. - - `text: string` + - `"auto"` - The text to type. + - `"low"` - - `type: "type"` + - `output_compression: optional number` - Specifies the event type. For a type action, this property is always set to `type`. + Compression level for the output image. Default: 100. - - `"type"` + - `output_format: optional "png" or "webp" or "jpeg"` - - `Wait object { type }` + The output format of the generated image. One of `png`, `webp`, or + `jpeg`. Default: `png`. - A wait action. + - `"png"` - - `type: "wait"` + - `"webp"` - Specifies the event type. For a wait action, this property is always set to `wait`. + - `"jpeg"` - - `"wait"` + - `partial_images: optional number` - - `actions: optional ComputerActionList` + Number of partial images to generate in streaming mode, from 0 (default value) to 3. - Flattened batched actions for `computer_use`. Each action includes an - `type` discriminator and action-specific fields. + - `quality: optional "low" or "medium" or "high" or "auto"` - - `Click object { button, type, x, 2 more }` + The quality of the generated image. One of `low`, `medium`, `high`, + or `auto`. Default: `auto`. - A click action. + - `"low"` - - `DoubleClick object { keys, type, x, y }` + - `"medium"` - A double click action. + - `"high"` - - `Drag object { path, type, keys }` + - `"auto"` - A drag action. + - `size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or "auto"` - - `Keypress object { keys, 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`. - A collection of keypresses the model would like to perform. + - `string` - - `Move object { type, x, y, keys }` + - `"1024x1024" or "1024x1536" or "1536x1024" or "auto"` - A mouse move action. + 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`. - - `Screenshot object { type }` + - `"1024x1024"` - A screenshot action. + - `"1024x1536"` - - `Scroll object { scroll_x, scroll_y, type, 3 more }` + - `"1536x1024"` - A scroll action. + - `"auto"` - - `Type object { text, type }` + - `LocalShell object { type }` - An action to type in text. + A tool that allows the model to execute shell commands in a local environment. - - `Wait object { type }` + - `type: "local_shell"` - A wait action. + The type of the local shell tool. Always `local_shell`. - - `ComputerCallOutput object { call_id, output, type, 3 more }` + - `"local_shell"` - The output of a computer tool call. + - `Shell object { type, allowed_callers, environment }` - - `call_id: string` + A tool that allows the model to execute shell commands. - The ID of the computer tool call that produced the output. + - `type: "shell"` - - `output: ResponseComputerToolCallOutputScreenshot` + The type of the shell tool. Always `shell`. - A computer screenshot image used with the computer use tool. + - `"shell"` - - `type: "computer_screenshot"` + - `allowed_callers: optional array of "direct" or "programmatic"` - Specifies the event type. For a computer screenshot, this property is - always set to `computer_screenshot`. + The tool invocation context(s). - - `"computer_screenshot"` + - `"direct"` - - `file_id: optional string` + - `"programmatic"` - The identifier of an uploaded file that contains the screenshot. + - `environment: optional ContainerAuto or LocalEnvironment or ContainerReference` - - `image_url: optional string` + - `ContainerAuto object { type, file_ids, memory_limit, 2 more }` - The URL of the screenshot image. + - `LocalEnvironment object { type, skills }` - - `type: "computer_call_output"` + - `ContainerReference object { container_id, type }` - The type of the computer tool call output. Always `computer_call_output`. + - `Custom object { name, type, allowed_callers, 3 more }` - - `"computer_call_output"` + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) - - `id: optional string` + - `name: string` - The ID of the computer tool call output. + The name of the custom tool, used to identify it in tool calls. - - `acknowledged_safety_checks: optional array of object { id, code, message }` + - `type: "custom"` - The safety checks reported by the API that have been acknowledged by the developer. + The type of the custom tool. Always `custom`. - - `id: string` + - `"custom"` - The ID of the pending safety check. + - `allowed_callers: optional array of "direct" or "programmatic"` - - `code: optional string` + The tool invocation context(s). - The type of the pending safety check. + - `"direct"` - - `message: optional string` + - `"programmatic"` - Details about the pending safety check. + - `defer_loading: optional boolean` - - `status: optional "in_progress" or "completed" or "incomplete"` + Whether this tool should be deferred and discovered via tool search. - The status of the message input. One of `in_progress`, `completed`, or `incomplete`. Populated when input items are returned via API. + - `description: optional string` - - `"in_progress"` + Optional description of the custom tool, used to provide more context. - - `"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. + - `format: optional CustomToolInputFormat` - - `"open_page"` + The input format for the custom tool. Default is unconstrained text. - - `url: optional string` + - `Namespace object { description, name, tools, type }` - The URL opened by the model. + Groups function/custom tools under a shared namespace. - - `FindInPage object { pattern, type, url }` + - `description: string` - Action type "find_in_page": Searches for a pattern within a loaded page. + A description of the namespace shown to the model. - - `pattern: string` + - `name: string` - The pattern or text to search for within the page. + The namespace name used in tool calls (for example, `crm`). - - `type: "find_in_page"` + - `tools: array of object { name, type, allowed_callers, 5 more } or object { name, type, allowed_callers, 3 more }` - The action type. + The function/custom tools available inside this namespace. - - `"find_in_page"` + - `Function object { name, type, allowed_callers, 5 more }` - - `url: string` + - `name: string` - The URL of the page searched for the pattern. + - `type: "function"` - - `status: "in_progress" or "searching" or "completed" or "failed"` + - `"function"` - The status of the web search tool call. + - `allowed_callers: optional array of "direct" or "programmatic"` - - `"in_progress"` + The tool invocation context(s). - - `"searching"` + - `"direct"` - - `"completed"` + - `"programmatic"` - - `"failed"` + - `defer_loading: optional boolean` - - `type: "web_search_call"` + Whether this function should be deferred and discovered via tool search. - The type of the web search tool call. Always `web_search_call`. + - `description: optional string` - - `"web_search_call"` + - `output_schema: optional map[unknown]` - - `FunctionCall object { arguments, call_id, name, 5 more }` + A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. - A tool call to run a function. See the - [function calling guide](/docs/guides/function-calling) for more information. + - `parameters: optional unknown` - - `arguments: string` + - `strict: optional boolean` - A JSON string of the arguments to pass to the function. + Whether to enforce strict parameter validation. If omitted, Responses attempts to use strict validation when the schema is compatible, and falls back to non-strict validation otherwise. - - `call_id: string` + - `Custom object { name, type, allowed_callers, 3 more }` - The unique ID of the function tool call generated by the model. + 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 function to run. - - - `type: "function_call"` - - The type of the function tool call. Always `function_call`. - - - `"function_call"` - - - `id: optional string` + The name of the custom tool, used to identify it in tool calls. - The unique ID of the function tool call. + - `type: "custom"` - - `caller: optional object { type } or object { caller_id, type }` + The type of the custom tool. Always `custom`. - The execution context that produced this tool call. + - `"custom"` - - `Direct object { type }` + - `allowed_callers: optional array of "direct" or "programmatic"` - - `type: "direct"` + The tool invocation context(s). - `"direct"` - - `Program object { caller_id, type }` + - `"programmatic"` - - `caller_id: string` + - `defer_loading: optional boolean` - The call ID of the program item that produced this tool call. + Whether this tool should be deferred and discovered via tool search. - - `type: "program"` + - `description: optional string` - - `"program"` + Optional description of the custom tool, used to provide more context. - - `namespace: optional string` + - `format: optional CustomToolInputFormat` - The namespace of the function to run. + The input format for the custom tool. Default is unconstrained text. - - `status: optional "in_progress" or "completed" or "incomplete"` + - `type: "namespace"` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + The type of the tool. Always `namespace`. - - `"in_progress"` + - `"namespace"` - - `"completed"` + - `ToolSearch object { type, description, execution, parameters }` - - `"incomplete"` + Hosted or BYOT tool search configuration for deferred tools. - - `FunctionCallOutput object { call_id, output, type, 3 more }` + - `type: "tool_search"` - The output of a function tool call. + The type of the tool. Always `tool_search`. - - `call_id: string` + - `"tool_search"` - The unique ID of the function tool call generated by the model. + - `description: optional string` - - `output: string or array of ResponseInputTextContent or ResponseInputImageContent or ResponseInputFileContent` + Description shown to the model for a client-executed tool search tool. - Text, image, or file output of the function tool call. + - `execution: optional "server" or "client"` - - `string` + Whether tool search is executed by the server or by the client. - A JSON string of the output of the function tool call. + - `"server"` - - `array of ResponseInputTextContent or ResponseInputImageContent or ResponseInputFileContent` + - `"client"` - An array of content outputs (text, image, file) for the function tool call. + - `parameters: optional unknown` - - `ResponseInputTextContent object { text, type, prompt_cache_breakpoint }` + Parameter schema for a client-executed tool search tool. - A text input to the model. + - `WebSearchPreview object { type, search_content_types, search_context_size, user_location }` - - `text: 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 text input to the model. + - `type: "web_search_preview" or "web_search_preview_2025_03_11"` - - `type: "input_text"` + The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. - The type of the input item. Always `input_text`. + - `"web_search_preview"` - - `"input_text"` + - `"web_search_preview_2025_03_11"` - - `prompt_cache_breakpoint: optional object { mode }` + - `search_content_types: optional array of "text" or "image"` - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + - `"text"` - - `mode: "explicit"` + - `"image"` - The breakpoint mode. Always `explicit`. + - `search_context_size: optional "low" or "medium" or "high"` - - `"explicit"` + 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. - - `ResponseInputImageContent object { type, detail, file_id, 2 more }` + - `"low"` - An image input to the model. Learn about [image inputs](/docs/guides/vision) + - `"medium"` - - `type: "input_image"` + - `"high"` - The type of the input item. Always `input_image`. + - `user_location: optional object { type, city, country, 2 more }` - - `"input_image"` + The user's location. - - `detail: optional "low" or "high" or "auto" or "original"` + - `type: "approximate"` - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + The type of location approximation. Always `approximate`. - - `"low"` + - `"approximate"` - - `"high"` + - `city: optional string` - - `"auto"` + Free text input for the city of the user, e.g. `San Francisco`. - - `"original"` + - `country: optional string` - - `file_id: optional string` + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - The ID of the file to be sent to the model. + - `region: optional string` - - `image_url: optional string` + Free text input for the region of the user, e.g. `California`. - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + - `timezone: optional string` - - `prompt_cache_breakpoint: optional object { mode }` + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + - `ApplyPatch object { type, allowed_callers }` - - `mode: "explicit"` + Allows the assistant to create, delete, or update files using unified diffs. - The breakpoint mode. Always `explicit`. + - `type: "apply_patch"` - - `"explicit"` + The type of the tool. Always `apply_patch`. - - `ResponseInputFileContent object { type, detail, file_data, 4 more }` + - `"apply_patch"` - A file input to the model. + - `allowed_callers: optional array of "direct" or "programmatic"` - - `type: "input_file"` + The tool invocation context(s). - The type of the input item. Always `input_file`. + - `"direct"` - - `"input_file"` + - `"programmatic"` - - `detail: optional "auto" or "low" or "high"` + - `type: "additional_tools"` - The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. + The type of the item. Always `additional_tools`. - - `"auto"` + - `"additional_tools"` - - `"low"` + - `FunctionCallOutput object { call_id, output, type, 3 more }` - - `"high"` + The output of a function tool call. - - `file_data: optional string` + - `call_id: string` - The base64-encoded data of the file to be sent to the model. + The unique ID of the function tool call generated by the model. - - `file_id: optional string` + - `output: string or array of ResponseInputText or ResponseInputImage or ResponseInputFile` - The ID of the file to be sent to the model. + The output from the function call generated by your code. + Can be a string or an list of output content. - - `file_url: optional string` + - `StringOutput = string` - The URL of the file to be sent to the model. + A string of the output of the function call. - - `filename: optional string` + - `OutputContentList = array of ResponseInputText or ResponseInputImage or ResponseInputFile` - The name of the file to be sent to the model. + Text, image, or file output of the function call. - - `prompt_cache_breakpoint: optional object { mode }` + - `ResponseInputText object { text, type, prompt_cache_breakpoint }` - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + A text input to the model. - - `mode: "explicit"` + - `ResponseInputImage object { detail, type, file_id, 2 more }` - The breakpoint mode. Always `explicit`. + An image input to the model. Learn about [image inputs](/docs/guides/vision). - - `"explicit"` + - `ResponseInputFile object { type, detail, file_data, 4 more }` + + A file input to the model. - `type: "function_call_output"` @@ -16948,7 +16110,8 @@ Retrieves a model response with the given ID. - `id: optional string` - The unique ID of the function tool call output. Populated when this item is returned via API. + The unique ID of the function tool call output. Populated when this item + is returned via API. - `caller: optional object { type } or object { caller_id, type }` @@ -16976,7 +16139,8 @@ Retrieves a model response with the given ID. - `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. + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - `"in_progress"` @@ -16984,2023 +16148,2147 @@ Retrieves a model response with the given ID. - `"incomplete"` - - `ToolSearchCall object { arguments, type, id, 3 more }` + - `FileSearchCall object { id, queries, status, 2 more }` - - `arguments: unknown` + The results of a file search tool call. See the + [file search guide](/docs/guides/tools-file-search) for more information. - The arguments supplied to the tool search call. + - `id: string` - - `type: "tool_search_call"` + The unique ID of the file search tool call. - The item type. Always `tool_search_call`. + - `queries: array of string` - - `"tool_search_call"` + The queries used to search for files. - - `id: optional string` + - `status: "in_progress" or "searching" or "completed" or 2 more` - The unique ID of this tool search call. + The status of the file search tool call. One of `in_progress`, + `searching`, `incomplete` or `failed`, - - `call_id: optional string` + - `"in_progress"` - The unique ID of the tool search call generated by the model. + - `"searching"` - - `execution: optional "server" or "client"` + - `"completed"` - Whether tool search was executed by the server or by the client. + - `"incomplete"` - - `"server"` + - `"failed"` - - `"client"` + - `type: "file_search_call"` - - `status: optional "in_progress" or "completed" or "incomplete"` + The type of the file search tool call. Always `file_search_call`. - The status of the tool search call. + - `"file_search_call"` - - `"in_progress"` + - `results: optional array of object { attributes, file_id, filename, 2 more }` - - `"completed"` + The results of the file search tool call. - - `"incomplete"` + - `attributes: optional map[string or number or boolean]` - - `ToolSearchOutput object { tools, type, id, 3 more }` + 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. - - `tools: array of object { name, parameters, strict, 5 more } or object { type, vector_store_ids, filters, 2 more } or object { type } or 13 more` + - `string` - The loaded tool definitions returned by the tool search output. + - `number` - - `Function object { name, parameters, strict, 5 more }` + - `boolean` - 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). + - `file_id: optional string` - - `name: string` + The unique ID of the file. - The name of the function to call. + - `filename: optional string` - - `parameters: map[unknown]` + The name of the file. - A JSON schema object describing the parameters of the function. + - `score: optional number` - - `strict: boolean` + The relevance score of the file - a value between 0 and 1. - Whether strict parameter validation is enforced for this function tool. + - `text: optional string` - - `type: "function"` + The text that was retrieved from the file. - The type of the function tool. Always `function`. + - `WebSearchCall object { id, action, status, type }` - - `"function"` + The results of a web search tool call. See the + [web search guide](/docs/guides/tools-web-search) for more information. - - `allowed_callers: optional array of "direct" or "programmatic"` + - `id: string` - The tool invocation context(s). + The unique ID of the web search tool call. - - `"direct"` + - `action: object { type, queries, query, sources } or object { type, url } or object { pattern, type, url }` - - `"programmatic"` + 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). - - `defer_loading: optional boolean` + - `Search object { type, queries, query, sources }` - Whether this function is deferred and loaded via tool search. + Action type "search" - Performs a web search query. - - `description: optional string` + - `type: "search"` - A description of the function. Used by the model to determine whether or not to call the function. + The action type. - - `output_schema: optional map[unknown]` + - `"search"` - A JSON schema object describing the JSON value encoded in string outputs for this function. + - `queries: optional array of string` - - `FileSearch object { type, vector_store_ids, filters, 2 more }` + The search queries. - 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). + - `query: optional string` - - `type: "file_search"` + The search query. - The type of the file search tool. Always `file_search`. + - `sources: optional array of object { type, url }` - - `"file_search"` + The sources used in the search. - - `vector_store_ids: array of string` + - `type: "url"` - The IDs of the vector stores to search. + The type of source. Always `url`. - - `filters: optional ComparisonFilter or CompoundFilter` + - `"url"` - A filter to apply. + - `url: string` - - `ComparisonFilter object { key, type, value }` + The URL of the source. - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + - `OpenPage object { type, url }` - - `key: string` + Action type "open_page" - Opens a specific URL from search results. - The key to compare against the value. + - `type: "open_page"` - - `type: "eq" or "ne" or "gt" or 5 more` + The action type. - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + - `"open_page"` - - `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 + - `url: optional string` - - `"eq"` + The URL opened by the model. - - `"ne"` + - `FindInPage object { pattern, type, url }` - - `"gt"` + Action type "find_in_page": Searches for a pattern within a loaded page. - - `"gte"` + - `pattern: string` - - `"lt"` + The pattern or text to search for within the page. - - `"lte"` + - `type: "find_in_page"` - - `"in"` + The action type. - - `"nin"` + - `"find_in_page"` - - `value: string or number or boolean or array of string or number` + - `url: string` - The value to compare against the attribute key; supports string, number, or boolean types. + The URL of the page searched for the pattern. - - `string` + - `status: "in_progress" or "searching" or "completed" or "failed"` - - `number` + The status of the web search tool call. - - `boolean` + - `"in_progress"` - - `array of string or number` + - `"searching"` - - `string` + - `"completed"` - - `number` + - `"failed"` - - `CompoundFilter object { filters, type }` + - `type: "web_search_call"` - Combine multiple filters using `and` or `or`. + The type of the web search tool call. Always `web_search_call`. - - `filters: array of ComparisonFilter or unknown` + - `"web_search_call"` - Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. + - `ImageGenerationCall object { id, result, status, type }` - - `ComparisonFilter object { key, type, value }` + An image generation request made by the model. - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + - `id: string` - - `unknown` + The unique ID of the image generation call. - - `type: "and" or "or"` + - `result: string` - Type of operation: `and` or `or`. + The generated image encoded in base64. - - `"and"` + - `status: "in_progress" or "completed" or "generating" or "failed"` - - `"or"` + The status of the image generation call. - - `max_num_results: optional number` + - `"in_progress"` - The maximum number of results to return. This number should be between 1 and 50 inclusive. + - `"completed"` - - `ranking_options: optional object { hybrid_search, ranker, score_threshold }` + - `"generating"` - Ranking options for search. + - `"failed"` - - `hybrid_search: optional object { embedding_weight, text_weight }` + - `type: "image_generation_call"` - Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. + The type of the image generation call. Always `image_generation_call`. - - `embedding_weight: number` + - `"image_generation_call"` - The weight of the embedding in the reciprocal ranking fusion. + - `ComputerCall object { id, call_id, pending_safety_checks, 4 more }` - - `text_weight: number` + A tool call to a computer use tool. See the + [computer use guide](/docs/guides/tools-computer-use) for more information. - The weight of the text in the reciprocal ranking fusion. + - `id: string` - - `ranker: optional "auto" or "default-2024-11-15"` + The unique ID of the computer call. - The ranker to use for the file search. + - `call_id: string` - - `"auto"` + An identifier used when responding to the tool call with output. - - `"default-2024-11-15"` + - `pending_safety_checks: array of object { id, code, message }` - - `score_threshold: optional number` + The pending safety checks for the computer 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. + - `id: string` - - `Computer object { type }` + The ID of the pending safety check. - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `code: optional string` - - `type: "computer"` + The type of the pending safety check. - The type of the computer tool. Always `computer`. + - `message: optional string` - - `"computer"` + Details about the pending safety check. - - `ComputerUsePreview object { display_height, display_width, environment, type }` + - `status: "in_progress" or "completed" or "incomplete"` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `display_height: number` + - `"in_progress"` - The height of the computer display. + - `"completed"` - - `display_width: number` + - `"incomplete"` - The width of the computer display. + - `type: "computer_call"` - - `environment: "windows" or "mac" or "linux" or 2 more` + The type of the computer call. Always `computer_call`. - The type of computer environment to control. + - `"computer_call"` - - `"windows"` + - `action: optional ComputerAction` - - `"mac"` + A click action. - - `"linux"` + - `Click object { button, type, x, 2 more }` - - `"ubuntu"` + A click action. - - `"browser"` + - `button: "left" or "right" or "wheel" or 2 more` - - `type: "computer_use_preview"` + Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. - The type of the computer use tool. Always `computer_use_preview`. + - `"left"` - - `"computer_use_preview"` + - `"right"` - - `WebSearch object { type, filters, search_context_size, user_location }` + - `"wheel"` - Search the Internet for sources related to the prompt. Learn more about the - [web search tool](/docs/guides/tools-web-search). + - `"back"` - - `type: "web_search" or "web_search_2025_08_26"` + - `"forward"` - The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. + - `type: "click"` - - `"web_search"` + Specifies the event type. For a click action, this property is always `click`. - - `"web_search_2025_08_26"` + - `"click"` - - `filters: optional object { allowed_domains }` + - `x: number` - Filters for the search. + The x-coordinate where the click occurred. - - `allowed_domains: optional array of string` + - `y: number` - Allowed domains for the search. If not provided, all domains are allowed. - Subdomains of the provided domains are allowed as well. + The y-coordinate where the click occurred. - Example: `["pubmed.ncbi.nlm.nih.gov"]` + - `keys: optional array of string` - - `search_context_size: optional "low" or "medium" or "high"` + The keys being held while clicking. - 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. + - `DoubleClick object { keys, type, x, y }` - - `"low"` + A double click action. - - `"medium"` + - `keys: array of string` - - `"high"` + The keys being held while double-clicking. - - `user_location: optional object { city, country, region, 2 more }` + - `type: "double_click"` - The approximate location of the user. + Specifies the event type. For a double click action, this property is always set to `double_click`. - - `city: optional string` + - `"double_click"` - Free text input for the city of the user, e.g. `San Francisco`. + - `x: number` - - `country: optional string` + The x-coordinate where the double click occurred. - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + - `y: number` - - `region: optional string` + The y-coordinate where the double click occurred. - Free text input for the region of the user, e.g. `California`. + - `Drag object { path, type, keys }` - - `timezone: optional string` + A drag action. - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + - `path: array of object { x, y }` - - `type: optional "approximate"` + An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg - The type of location approximation. Always `approximate`. + ``` + [ + { x: 100, y: 200 }, + { x: 200, y: 300 } + ] + ``` - - `"approximate"` + - `x: number` - - `Mcp object { server_label, type, allowed_callers, 9 more }` + The x-coordinate. - Give the model access to additional tools via remote Model Context Protocol - (MCP) servers. [Learn more about MCP](/docs/guides/tools-remote-mcp). + - `y: number` - - `server_label: string` + The y-coordinate. - A label for this MCP server, used to identify it in tool calls. + - `type: "drag"` - - `type: "mcp"` + Specifies the event type. For a drag action, this property is always set to `drag`. - The type of the MCP tool. Always `mcp`. + - `"drag"` - - `"mcp"` + - `keys: optional array of string` - - `allowed_callers: optional array of "direct" or "programmatic"` + The keys being held while dragging the mouse. - The tool invocation context(s). + - `Keypress object { keys, type }` - - `"direct"` + A collection of keypresses the model would like to perform. - - `"programmatic"` + - `keys: array of string` - - `allowed_tools: optional array of string or object { read_only, tool_names }` + The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. - List of allowed tool names or a filter object. + - `type: "keypress"` - - `McpAllowedTools = array of string` + Specifies the event type. For a keypress action, this property is always set to `keypress`. - A string array of allowed tool names + - `"keypress"` - - `McpToolFilter object { read_only, tool_names }` + - `Move object { type, x, y, keys }` - A filter object to specify which tools are allowed. + A mouse move action. - - `read_only: optional boolean` + - `type: "move"` - 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. + Specifies the event type. For a move action, this property is always set to `move`. - - `tool_names: optional array of string` + - `"move"` - List of allowed tool names. + - `x: number` - - `authorization: optional string` + The x-coordinate to move to. - 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. + - `y: number` - - `connector_id: optional "connector_dropbox" or "connector_gmail" or "connector_googlecalendar" or 5 more` + The y-coordinate to move to. - Identifier for service connectors, like those available in ChatGPT. One of - `server_url`, `connector_id`, or `tunnel_id` must be provided. Learn more - about service connectors [here](/docs/guides/tools-remote-mcp#connectors). + - `keys: optional array of string` - Currently supported `connector_id` values are: + The keys being held while moving the mouse. - - 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` + - `Screenshot object { type }` - - `"connector_dropbox"` + A screenshot action. - - `"connector_gmail"` + - `type: "screenshot"` - - `"connector_googlecalendar"` + Specifies the event type. For a screenshot action, this property is always set to `screenshot`. - - `"connector_googledrive"` + - `"screenshot"` - - `"connector_microsoftteams"` + - `Scroll object { scroll_x, scroll_y, type, 3 more }` - - `"connector_outlookcalendar"` + A scroll action. - - `"connector_outlookemail"` + - `scroll_x: number` - - `"connector_sharepoint"` + The horizontal scroll distance. - - `defer_loading: optional boolean` + - `scroll_y: number` - Whether this MCP tool is deferred and discovered via tool search. + The vertical scroll distance. - - `headers: optional map[string]` + - `type: "scroll"` - Optional HTTP headers to send to the MCP server. Use for authentication - or other purposes. + Specifies the event type. For a scroll action, this property is always set to `scroll`. - - `require_approval: optional object { always, never } or "always" or "never"` + - `"scroll"` - Specify which of the MCP server's tools require approval. + - `x: number` - - `McpToolApprovalFilter object { always, never }` + The x-coordinate where the scroll occurred. - Specify which of the MCP server's tools require approval. Can be - `always`, `never`, or a filter object associated with tools - that require approval. + - `y: number` - - `always: optional object { read_only, tool_names }` + The y-coordinate where the scroll occurred. - A filter object to specify which tools are allowed. + - `keys: optional array of string` - - `read_only: optional boolean` + The keys being held while scrolling. - 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 object { text, type }` - - `tool_names: optional array of string` + An action to type in text. - List of allowed tool names. + - `text: string` - - `never: optional object { read_only, tool_names }` + The text to type. - A filter object to specify which tools are allowed. + - `type: "type"` - - `read_only: optional boolean` + Specifies the event type. For a type action, this property is always set to `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. + - `"type"` - - `tool_names: optional array of string` + - `Wait object { type }` - List of allowed tool names. + A wait action. - - `McpToolApprovalSetting = "always" or "never"` + - `type: "wait"` - 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. + Specifies the event type. For a wait action, this property is always set to `wait`. - - `"always"` + - `"wait"` - - `"never"` + - `actions: optional ComputerActionList` - - `server_description: optional string` + Flattened batched actions for `computer_use`. Each action includes an + `type` discriminator and action-specific fields. - Optional description of the MCP server, used to provide more context. + - `Click object { button, type, x, 2 more }` - - `server_url: optional string` + A click action. - The URL for the MCP server. One of `server_url`, `connector_id`, or - `tunnel_id` must be provided. + - `DoubleClick object { keys, type, x, y }` - - `tunnel_id: optional string` + A double click action. - The Secure MCP Tunnel ID to use instead of a direct server URL. One of - `server_url`, `connector_id`, or `tunnel_id` must be provided. + - `Drag object { path, type, keys }` - - `CodeInterpreter object { container, type, allowed_callers }` + A drag action. - A tool that runs Python code to help generate a response to a prompt. + - `Keypress object { keys, type }` - - `container: string or object { type, file_ids, memory_limit, network_policy }` + A collection of keypresses the model would like to perform. - 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. + - `Move object { type, x, y, keys }` - - `string` + A mouse move action. - The container ID. + - `Screenshot object { type }` - - `CodeInterpreterToolAuto object { type, file_ids, memory_limit, network_policy }` + A screenshot action. - Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. + - `Scroll object { scroll_x, scroll_y, type, 3 more }` - - `type: "auto"` + A scroll action. - Always `auto`. + - `Type object { text, type }` - - `"auto"` + An action to type in text. - - `file_ids: optional array of string` + - `Wait object { type }` - An optional list of uploaded files to make available to your code. + A wait action. - - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` + - `ComputerCallOutput object { id, call_id, output, 4 more }` - The memory limit for the code interpreter container. + - `id: string` - - `"1g"` + The unique ID of the computer call tool output. - - `"4g"` + - `call_id: string` - - `"16g"` + The ID of the computer tool call that produced the output. - - `"64g"` + - `output: ResponseComputerToolCallOutputScreenshot` - - `network_policy: optional ContainerNetworkPolicyDisabled or ContainerNetworkPolicyAllowlist` + A computer screenshot image used with the computer use tool. - Network access policy for the container. + - `type: "computer_screenshot"` - - `ContainerNetworkPolicyDisabled object { type }` + Specifies the event type. For a computer screenshot, this property is + always set to `computer_screenshot`. - - `type: "disabled"` + - `"computer_screenshot"` - Disable outbound network access. Always `disabled`. + - `file_id: optional string` - - `"disabled"` + The identifier of an uploaded file that contains the screenshot. - - `ContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` + - `image_url: optional string` - - `allowed_domains: array of string` + The URL of the screenshot image. - A list of allowed domains when type is `allowlist`. + - `status: "completed" or "incomplete" or "failed" or "in_progress"` - - `type: "allowlist"` + The status of the message input. One of `in_progress`, `completed`, or + `incomplete`. Populated when input items are returned via API. - Allow outbound network access only to specified domains. Always `allowlist`. + - `"completed"` - - `"allowlist"` + - `"incomplete"` - - `domain_secrets: optional array of ContainerNetworkPolicyDomainSecret` + - `"failed"` - Optional domain-scoped secrets for allowlisted domains. + - `"in_progress"` - - `domain: string` + - `type: "computer_call_output"` - The domain associated with the secret. + The type of the computer tool call output. Always `computer_call_output`. - - `name: string` + - `"computer_call_output"` - The name of the secret to inject for the domain. + - `acknowledged_safety_checks: optional array of object { id, code, message }` - - `value: string` + The safety checks reported by the API that have been acknowledged by the + developer. - The secret value to inject for the domain. + - `id: string` - - `type: "code_interpreter"` + The ID of the pending safety check. - The type of the code interpreter tool. Always `code_interpreter`. + - `code: optional string` - - `"code_interpreter"` + The type of the pending safety check. - - `allowed_callers: optional array of "direct" or "programmatic"` + - `message: optional string` - The tool invocation context(s). + Details about the pending safety check. - - `"direct"` + - `created_by: optional string` - - `"programmatic"` + The identifier of the actor that created the item. - - `ProgrammaticToolCalling object { type }` + - `Reasoning object { id, summary, type, 3 more }` - - `type: "programmatic_tool_calling"` + 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 tool. Always `programmatic_tool_calling`. + - `id: string` - - `"programmatic_tool_calling"` + The unique identifier of the reasoning content. - - `ImageGeneration object { type, action, background, 9 more }` + - `summary: array of SummaryTextContent` - A tool that generates images using the GPT image models. + Reasoning summary content. - - `type: "image_generation"` + - `text: string` - The type of the image generation tool. Always `image_generation`. + A summary of the reasoning output from the model so far. - - `"image_generation"` + - `type: "summary_text"` - - `action: optional "generate" or "edit" or "auto"` + The type of the object. Always `summary_text`. - Whether to generate a new image or edit an existing image. Default: `auto`. + - `type: "reasoning"` - - `"generate"` + The type of the object. Always `reasoning`. - - `"edit"` + - `"reasoning"` - - `"auto"` + - `content: optional array of object { text, type }` - - `background: optional "transparent" or "opaque" or "auto"` + Reasoning text content. - Background type for the generated image. One of `transparent`, - `opaque`, or `auto`. Default: `auto`. + - `text: string` - - `"transparent"` + The reasoning text from the model. - - `"opaque"` + - `type: "reasoning_text"` - - `"auto"` + The type of the reasoning text. Always `reasoning_text`. - - `input_fidelity: optional "high" or "low"` + - `"reasoning_text"` - 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`. + - `encrypted_content: optional string` - - `"high"` + The encrypted content of the reasoning item. This is populated by default + for reasoning items returned by `POST /v1/responses` and WebSocket + `response.create` requests. - - `"low"` + - `status: optional "in_progress" or "completed" or "incomplete"` - - `input_image_mask: optional object { file_id, image_url }` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - Optional mask for inpainting. Contains `image_url` - (string, optional) and `file_id` (string, optional). + - `"in_progress"` - - `file_id: optional string` + - `"completed"` - File ID for the mask image. + - `"incomplete"` - - `image_url: optional string` + - `Compaction object { id, encrypted_content, type, created_by }` - Base64-encoded mask image. + A compaction item generated by the [`v1/responses/compact` API](/docs/api-reference/responses/compact). - - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` + - `id: string` - The image generation model to use. Default: `gpt-image-1`. + The unique ID of the compaction item. - - `string` + - `encrypted_content: string` - - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` + The encrypted content that was produced by compaction. - The image generation model to use. Default: `gpt-image-1`. + - `type: "compaction"` - - `"gpt-image-1"` + The type of the item. Always `compaction`. - - `"gpt-image-1-mini"` + - `"compaction"` - - `"gpt-image-1.5"` + - `created_by: optional string` - - `moderation: optional "auto" or "low"` + The identifier of the actor that created the item. - Moderation level for the generated image. Default: `auto`. + - `CodeInterpreterCall object { id, code, container_id, 3 more }` - - `"auto"` + A tool call to run code. - - `"low"` + - `id: string` - - `output_compression: optional number` + The unique ID of the code interpreter tool call. - Compression level for the output image. Default: 100. + - `code: string` - - `output_format: optional "png" or "webp" or "jpeg"` + The code to run, or null if not available. - The output format of the generated image. One of `png`, `webp`, or - `jpeg`. Default: `png`. + - `container_id: string` - - `"png"` + The ID of the container used to run the code. - - `"webp"` + - `outputs: array of object { logs, type } or object { type, url }` - - `"jpeg"` + The outputs generated by the code interpreter, such as logs or images. + Can be null if no outputs are available. - - `partial_images: optional number` + - `Logs object { logs, type }` - Number of partial images to generate in streaming mode, from 0 (default value) to 3. + The logs output from the code interpreter. - - `quality: optional "low" or "medium" or "high" or "auto"` + - `logs: string` - The quality of the generated image. One of `low`, `medium`, `high`, - or `auto`. Default: `auto`. + The logs output from the code interpreter. - - `"low"` + - `type: "logs"` - - `"medium"` + The type of the output. Always `logs`. - - `"high"` + - `"logs"` - - `"auto"` + - `Image object { type, url }` - - `size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or "auto"` + The image output from the code interpreter. - 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: "image"` - - `string` + The type of the output. Always `image`. - - `"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`. + - `url: string` - - `"1024x1024"` + The URL of the image output from the code interpreter. - - `"1024x1536"` + - `status: "in_progress" or "completed" or "incomplete" or 2 more` - - `"1536x1024"` + The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. - - `"auto"` + - `"in_progress"` - - `LocalShell object { type }` + - `"completed"` - A tool that allows the model to execute shell commands in a local environment. + - `"incomplete"` - - `type: "local_shell"` + - `"interpreting"` - The type of the local shell tool. Always `local_shell`. + - `"failed"` - - `"local_shell"` + - `type: "code_interpreter_call"` - - `Shell object { type, allowed_callers, environment }` + The type of the code interpreter tool call. Always `code_interpreter_call`. - A tool that allows the model to execute shell commands. + - `"code_interpreter_call"` - - `type: "shell"` + - `LocalShellCall object { id, action, call_id, 2 more }` - The type of the shell tool. Always `shell`. + A tool call to run a command on the local shell. - - `"shell"` + - `id: string` - - `allowed_callers: optional array of "direct" or "programmatic"` + The unique ID of the local shell call. - The tool invocation context(s). + - `action: object { command, env, type, 3 more }` - - `"direct"` + Execute a shell command on the server. - - `"programmatic"` + - `command: array of string` - - `environment: optional ContainerAuto or LocalEnvironment or ContainerReference` + The command to run. - - `ContainerAuto object { type, file_ids, memory_limit, 2 more }` + - `env: map[string]` - - `type: "container_auto"` + Environment variables to set for the command. - Automatically creates a container for this request + - `type: "exec"` - - `"container_auto"` + The type of the local shell action. Always `exec`. - - `file_ids: optional array of string` + - `"exec"` - An optional list of uploaded files to make available to your code. + - `timeout_ms: optional number` - - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` + Optional timeout in milliseconds for the command. - The memory limit for the container. + - `user: optional string` - - `"1g"` + Optional user to run the command as. - - `"4g"` + - `working_directory: optional string` - - `"16g"` + Optional working directory to run the command in. - - `"64g"` + - `call_id: string` - - `network_policy: optional ContainerNetworkPolicyDisabled or ContainerNetworkPolicyAllowlist` + The unique ID of the local shell tool call generated by the model. - Network access policy for the container. + - `status: "in_progress" or "completed" or "incomplete"` - - `ContainerNetworkPolicyDisabled object { type }` + The status of the local shell call. - - `ContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` + - `"in_progress"` - - `skills: optional array of SkillReference or InlineSkill` + - `"completed"` - An optional list of skills referenced by id or inline data. + - `"incomplete"` - - `SkillReference object { skill_id, type, version }` + - `type: "local_shell_call"` - - `skill_id: string` + The type of the local shell call. Always `local_shell_call`. - The ID of the referenced skill. + - `"local_shell_call"` - - `type: "skill_reference"` + - `LocalShellCallOutput object { id, output, type, status }` - References a skill created with the /v1/skills endpoint. + The output of a local shell tool call. - - `"skill_reference"` + - `id: string` - - `version: optional string` + The unique ID of the local shell tool call generated by the model. - Optional skill version. Use a positive integer or 'latest'. Omit for default. + - `output: string` - - `InlineSkill object { description, name, source, type }` + A JSON string of the output of the local shell tool call. - - `description: string` + - `type: "local_shell_call_output"` - The description of the skill. + The type of the local shell tool call output. Always `local_shell_call_output`. - - `name: string` + - `"local_shell_call_output"` - The name of the skill. + - `status: optional "in_progress" or "completed" or "incomplete"` - - `source: InlineSkillSource` + The status of the item. One of `in_progress`, `completed`, or `incomplete`. - Inline skill payload + - `"in_progress"` - - `data: string` + - `"completed"` - Base64-encoded skill zip bundle. + - `"incomplete"` - - `media_type: "application/zip"` + - `ShellCall object { id, action, call_id, 5 more }` - The media type of the inline skill payload. Must be `application/zip`. + A tool call that executes one or more shell commands in a managed environment. - - `"application/zip"` + - `id: string` - - `type: "base64"` + The unique ID of the shell tool call. Populated when this item is returned via API. - The type of the inline skill source. Must be `base64`. + - `action: object { commands, max_output_length, timeout_ms }` - - `"base64"` + The shell commands and limits that describe how to run the tool call. - - `type: "inline"` + - `commands: array of string` - Defines an inline skill for this request. + - `max_output_length: number` - - `"inline"` + Optional maximum number of characters to return from each command. - - `LocalEnvironment object { type, skills }` + - `timeout_ms: number` - - `type: "local"` + Optional timeout in milliseconds for the commands. - Use a local computer environment. + - `call_id: string` - - `"local"` + The unique ID of the shell tool call generated by the model. - - `skills: optional array of LocalSkill` + - `environment: ResponseLocalEnvironment or ResponseContainerReference` - An optional list of skills. + Represents the use of a local environment to perform shell actions. - - `description: string` + - `ResponseLocalEnvironment object { type }` - The description of the skill. + Represents the use of a local environment to perform shell actions. - - `name: string` + - `type: "local"` - The name of the skill. + The environment type. Always `local`. - - `path: string` + - `"local"` - The path to the directory containing the skill. + - `ResponseContainerReference object { container_id, type }` - - `ContainerReference object { container_id, type }` + Represents a container created with /v1/containers. - `container_id: string` - The ID of the referenced container. - - `type: "container_reference"` - References a container created with the /v1/containers endpoint + The environment type. Always `container_reference`. - `"container_reference"` - - `Custom object { name, type, allowed_callers, 3 more }` - - A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) - - - `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"` - - `allowed_callers: optional array of "direct" or "programmatic"` + - `type: "shell_call"` - The tool invocation context(s). + The type of the item. Always `shell_call`. - - `"direct"` + - `"shell_call"` - - `"programmatic"` + - `caller: optional object { type } or object { caller_id, type }` - - `defer_loading: optional boolean` + The execution context that produced this tool call. - Whether this tool should be deferred and discovered via tool search. + - `Direct object { type }` - - `description: optional string` + - `type: "direct"` - Optional description of the custom tool, used to provide more context. + - `"direct"` - - `format: optional CustomToolInputFormat` + - `Program object { caller_id, type }` - The input format for the custom tool. Default is unconstrained text. + - `caller_id: string` - - `Text object { type }` + The call ID of the program item that produced this tool call. - Unconstrained free-form text. + - `type: "program"` - - `type: "text"` + - `"program"` - Unconstrained text format. Always `text`. + - `created_by: optional string` - - `"text"` + The ID of the entity that created this tool call. - - `Grammar object { definition, syntax, type }` + - `ShellCallOutput object { id, call_id, max_output_length, 5 more }` - A grammar defined by the user. + The output of a shell tool call that was emitted. - - `definition: string` + - `id: string` - The grammar definition. + The unique ID of the shell call output. Populated when this item is returned via API. - - `syntax: "lark" or "regex"` + - `call_id: string` - The syntax of the grammar definition. One of `lark` or `regex`. + The unique ID of the shell tool call generated by the model. - - `"lark"` + - `max_output_length: number` - - `"regex"` + The maximum length of the shell command output. This is generated by the model and should be passed back with the raw output. - - `type: "grammar"` + - `output: array of object { outcome, stderr, stdout, created_by }` - Grammar format. Always `grammar`. + An array of shell call output contents - - `"grammar"` + - `outcome: object { type } or object { exit_code, type }` - - `Namespace object { description, name, tools, type }` + Represents either an exit outcome (with an exit code) or a timeout outcome for a shell call output chunk. - Groups function/custom tools under a shared namespace. + - `Timeout object { type }` - - `description: string` + Indicates that the shell call exceeded its configured time limit. - A description of the namespace shown to the model. + - `type: "timeout"` - - `name: string` + The outcome type. Always `timeout`. - The namespace name used in tool calls (for example, `crm`). + - `"timeout"` - - `tools: array of object { name, type, allowed_callers, 5 more } or object { name, type, allowed_callers, 3 more }` + - `Exit object { exit_code, type }` - The function/custom tools available inside this namespace. + Indicates that the shell commands finished and returned an exit code. - - `Function object { name, type, allowed_callers, 5 more }` + - `exit_code: number` - - `name: string` + Exit code from the shell process. - - `type: "function"` + - `type: "exit"` - - `"function"` + The outcome type. Always `exit`. - - `allowed_callers: optional array of "direct" or "programmatic"` + - `"exit"` - The tool invocation context(s). + - `stderr: string` - - `"direct"` + The standard error output that was captured. - - `"programmatic"` + - `stdout: string` - - `defer_loading: optional boolean` + The standard output that was captured. - Whether this function should be deferred and discovered via tool search. + - `created_by: optional string` - - `description: optional string` + The identifier of the actor that created the item. - - `output_schema: optional map[unknown]` + - `status: "in_progress" or "completed" or "incomplete"` - A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. + The status of the shell call output. One of `in_progress`, `completed`, or `incomplete`. - - `parameters: optional unknown` + - `"in_progress"` - - `strict: optional boolean` + - `"completed"` - Whether to enforce strict parameter validation. If omitted, Responses attempts to use strict validation when the schema is compatible, and falls back to non-strict validation otherwise. + - `"incomplete"` - - `Custom object { name, type, allowed_callers, 3 more }` + - `type: "shell_call_output"` - 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 shell call output. Always `shell_call_output`. - - `name: string` + - `"shell_call_output"` - The name of the custom tool, used to identify it in tool calls. + - `caller: optional object { type } or object { caller_id, type }` - - `type: "custom"` + The execution context that produced this tool call. - The type of the custom tool. Always `custom`. + - `Direct object { type }` - - `"custom"` + - `type: "direct"` - - `allowed_callers: optional array of "direct" or "programmatic"` + - `"direct"` - The tool invocation context(s). + - `Program object { caller_id, type }` - - `"direct"` + - `caller_id: string` - - `"programmatic"` + The call ID of the program item that produced this tool call. - - `defer_loading: optional boolean` + - `type: "program"` - Whether this tool should be deferred and discovered via tool search. + - `"program"` - - `description: optional string` + - `created_by: optional string` - Optional description of the custom tool, used to provide more context. + The identifier of the actor that created the item. - - `format: optional CustomToolInputFormat` + - `ApplyPatchCall object { id, call_id, operation, 4 more }` - The input format for the custom tool. Default is unconstrained text. + A tool call that applies file diffs by creating, deleting, or updating files. - - `type: "namespace"` + - `id: string` - The type of the tool. Always `namespace`. + The unique ID of the apply patch tool call. Populated when this item is returned via API. - - `"namespace"` + - `call_id: string` - - `ToolSearch object { type, description, execution, parameters }` + The unique ID of the apply patch tool call generated by the model. - Hosted or BYOT tool search configuration for deferred tools. + - `operation: object { diff, path, type } or object { path, type } or object { diff, path, type }` - - `type: "tool_search"` + One of the create_file, delete_file, or update_file operations applied via apply_patch. - The type of the tool. Always `tool_search`. + - `CreateFile object { diff, path, type }` - - `"tool_search"` + Instruction describing how to create a file via the apply_patch tool. - - `description: optional string` + - `diff: string` - Description shown to the model for a client-executed tool search tool. + Diff to apply. - - `execution: optional "server" or "client"` + - `path: string` - Whether tool search is executed by the server or by the client. + Path of the file to create. - - `"server"` + - `type: "create_file"` - - `"client"` + Create a new file with the provided diff. - - `parameters: optional unknown` + - `"create_file"` - Parameter schema for a client-executed tool search tool. + - `DeleteFile object { path, type }` - - `WebSearchPreview object { type, search_content_types, search_context_size, user_location }` + Instruction describing how to delete a file via the apply_patch tool. - 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). + - `path: string` - - `type: "web_search_preview" or "web_search_preview_2025_03_11"` + Path of the file to delete. - The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. + - `type: "delete_file"` - - `"web_search_preview"` + Delete the specified file. - - `"web_search_preview_2025_03_11"` + - `"delete_file"` - - `search_content_types: optional array of "text" or "image"` + - `UpdateFile object { diff, path, type }` - - `"text"` + Instruction describing how to update a file via the apply_patch tool. - - `"image"` + - `diff: string` - - `search_context_size: optional "low" or "medium" or "high"` + Diff to apply. - 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. + - `path: string` - - `"low"` + Path of the file to update. - - `"medium"` + - `type: "update_file"` - - `"high"` + Update an existing file with the provided diff. - - `user_location: optional object { type, city, country, 2 more }` + - `"update_file"` - The user's location. + - `status: "in_progress" or "completed"` - - `type: "approximate"` + The status of the apply patch tool call. One of `in_progress` or `completed`. - The type of location approximation. Always `approximate`. + - `"in_progress"` - - `"approximate"` + - `"completed"` - - `city: optional string` + - `type: "apply_patch_call"` - Free text input for the city of the user, e.g. `San Francisco`. + The type of the item. Always `apply_patch_call`. - - `country: optional string` + - `"apply_patch_call"` - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + - `caller: optional object { type } or object { caller_id, type }` - - `region: optional string` + The execution context that produced this tool call. - Free text input for the region of the user, e.g. `California`. + - `Direct object { type }` - - `timezone: optional string` + - `type: "direct"` - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + - `"direct"` - - `ApplyPatch object { type, allowed_callers }` + - `Program object { caller_id, type }` - Allows the assistant to create, delete, or update files using unified diffs. + - `caller_id: string` - - `type: "apply_patch"` + The call ID of the program item that produced this tool call. - The type of the tool. Always `apply_patch`. + - `type: "program"` - - `"apply_patch"` + - `"program"` - - `allowed_callers: optional array of "direct" or "programmatic"` + - `created_by: optional string` - The tool invocation context(s). + The ID of the entity that created this tool call. - - `"direct"` + - `ApplyPatchCallOutput object { id, call_id, status, 4 more }` - - `"programmatic"` + The output emitted by an apply patch tool call. - - `type: "tool_search_output"` + - `id: string` - The item type. Always `tool_search_output`. + The unique ID of the apply patch tool call output. Populated when this item is returned via API. - - `"tool_search_output"` + - `call_id: string` - - `id: optional string` + The unique ID of the apply patch tool call generated by the model. - The unique ID of this tool search output. + - `status: "completed" or "failed"` - - `call_id: optional string` + The status of the apply patch tool call output. One of `completed` or `failed`. - The unique ID of the tool search call generated by the model. + - `"completed"` - - `execution: optional "server" or "client"` + - `"failed"` - Whether tool search was executed by the server or by the client. + - `type: "apply_patch_call_output"` - - `"server"` + The type of the item. Always `apply_patch_call_output`. - - `"client"` + - `"apply_patch_call_output"` - - `status: optional "in_progress" or "completed" or "incomplete"` + - `caller: optional object { type } or object { caller_id, type }` - The status of the tool search output. + The execution context that produced this tool call. - - `"in_progress"` + - `Direct object { type }` - - `"completed"` + - `type: "direct"` - - `"incomplete"` + - `"direct"` - - `AdditionalTools object { role, tools, type, id }` + - `Program object { caller_id, type }` - - `role: "developer"` + - `caller_id: string` - The role that provided the additional tools. Only `developer` is supported. + The call ID of the program item that produced this tool call. - - `"developer"` + - `type: "program"` - - `tools: array of object { name, parameters, strict, 5 more } or object { type, vector_store_ids, filters, 2 more } or object { type } or 13 more` + - `"program"` - A list of additional tools made available at this item. + - `created_by: optional string` - - `Function object { name, parameters, strict, 5 more }` + The ID of the entity that created this tool call output. - Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). + - `output: optional string` - - `name: string` + Optional textual output returned by the apply patch tool. - The name of the function to call. + - `McpListTools object { id, server_label, tools, 2 more }` - - `parameters: map[unknown]` + A list of tools available on an MCP server. - A JSON schema object describing the parameters of the function. + - `id: string` - - `strict: boolean` + The unique ID of the list. - Whether strict parameter validation is enforced for this function tool. + - `server_label: string` - - `type: "function"` + The label of the MCP server. - The type of the function tool. Always `function`. + - `tools: array of object { input_schema, name, annotations, description }` - - `"function"` + The tools available on the server. - - `allowed_callers: optional array of "direct" or "programmatic"` + - `input_schema: unknown` - The tool invocation context(s). + The JSON schema describing the tool's input. - - `"direct"` + - `name: string` - - `"programmatic"` + The name of the tool. - - `defer_loading: optional boolean` + - `annotations: optional unknown` - Whether this function is deferred and loaded via tool search. + Additional annotations about the tool. - `description: optional string` - A description of the function. Used by the model to determine whether or not to call the function. + The description of the tool. - - `output_schema: optional map[unknown]` + - `type: "mcp_list_tools"` - A JSON schema object describing the JSON value encoded in string outputs for this function. + The type of the item. Always `mcp_list_tools`. - - `FileSearch object { type, vector_store_ids, filters, 2 more }` + - `"mcp_list_tools"` - 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). + - `error: optional string` - - `type: "file_search"` + Error message if the server could not list tools. - The type of the file search tool. Always `file_search`. + - `McpApprovalRequest object { id, arguments, name, 2 more }` - - `"file_search"` + A request for human approval of a tool invocation. - - `vector_store_ids: array of string` + - `id: string` - The IDs of the vector stores to search. + The unique ID of the approval request. - - `filters: optional ComparisonFilter or CompoundFilter` + - `arguments: string` - A filter to apply. + A JSON string of arguments for the tool. - - `ComparisonFilter object { key, type, value }` + - `name: string` - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + The name of the tool to run. - - `CompoundFilter object { filters, type }` + - `server_label: string` - Combine multiple filters using `and` or `or`. + The label of the MCP server making the request. - - `max_num_results: optional number` + - `type: "mcp_approval_request"` - The maximum number of results to return. This number should be between 1 and 50 inclusive. + The type of the item. Always `mcp_approval_request`. - - `ranking_options: optional object { hybrid_search, ranker, score_threshold }` + - `"mcp_approval_request"` - Ranking options for search. + - `McpApprovalResponse object { id, approval_request_id, approve, 2 more }` - - `hybrid_search: optional object { embedding_weight, text_weight }` + A response to an MCP approval request. - Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. + - `id: string` - - `embedding_weight: number` + The unique ID of the approval response - The weight of the embedding in the reciprocal ranking fusion. + - `approval_request_id: string` - - `text_weight: number` + The ID of the approval request being answered. - The weight of the text in the reciprocal ranking fusion. + - `approve: boolean` - - `ranker: optional "auto" or "default-2024-11-15"` + Whether the request was approved. - The ranker to use for the file search. + - `type: "mcp_approval_response"` - - `"auto"` + The type of the item. Always `mcp_approval_response`. - - `"default-2024-11-15"` + - `"mcp_approval_response"` - - `score_threshold: optional number` + - `reason: 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 reason for the decision. - - `Computer object { type }` + - `McpCall object { id, arguments, name, 6 more }` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + An invocation of a tool on an MCP server. - - `type: "computer"` + - `id: string` - The type of the computer tool. Always `computer`. + The unique ID of the tool call. - - `"computer"` + - `arguments: string` - - `ComputerUsePreview object { display_height, display_width, environment, type }` + A JSON string of the arguments passed to the tool. - 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 that was run. - The height of the computer display. + - `server_label: string` - - `display_width: number` + The label of the MCP server running the tool. - The width of the computer display. + - `type: "mcp_call"` - - `environment: "windows" or "mac" or "linux" or 2 more` + The type of the item. Always `mcp_call`. - The type of computer environment to control. + - `"mcp_call"` - - `"windows"` + - `approval_request_id: optional string` - - `"mac"` + 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. - - `"linux"` + - `error: optional string` - - `"ubuntu"` + The error from the tool call, if any. - - `"browser"` + - `output: optional string` - - `type: "computer_use_preview"` + The output from the tool call. - The type of the computer use tool. Always `computer_use_preview`. + - `status: optional "in_progress" or "completed" or "incomplete" or 2 more` - - `"computer_use_preview"` + The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. - - `WebSearch object { type, filters, search_context_size, user_location }` + - `"in_progress"` - Search the Internet for sources related to the prompt. Learn more about the - [web search tool](/docs/guides/tools-web-search). + - `"completed"` - - `type: "web_search" or "web_search_2025_08_26"` + - `"incomplete"` - The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. + - `"calling"` - - `"web_search"` + - `"failed"` - - `"web_search_2025_08_26"` + - `CustomToolCall object { call_id, input, name, 4 more }` - - `filters: optional object { allowed_domains }` + A call to a custom tool created by the model. - Filters for the search. + - `call_id: string` - - `allowed_domains: optional array of string` + An identifier used to map this custom tool call to a tool call output. - Allowed domains for the search. If not provided, all domains are allowed. - Subdomains of the provided domains are allowed as well. + - `input: string` - Example: `["pubmed.ncbi.nlm.nih.gov"]` + The input for the custom tool call generated by the model. - - `search_context_size: optional "low" or "medium" or "high"` + - `name: 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 name of the custom tool being called. - - `"low"` + - `type: "custom_tool_call"` - - `"medium"` + The type of the custom tool call. Always `custom_tool_call`. - - `"high"` + - `"custom_tool_call"` - - `user_location: optional object { city, country, region, 2 more }` + - `id: optional string` - The approximate location of the user. + The unique ID of the custom tool call in the OpenAI platform. - - `city: optional string` + - `caller: optional object { type } or object { caller_id, type }` - Free text input for the city of the user, e.g. `San Francisco`. + The execution context that produced this tool call. - - `country: optional string` + - `Direct object { type }` - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + - `type: "direct"` - - `region: optional string` + - `"direct"` - Free text input for the region of the user, e.g. `California`. + - `Program object { caller_id, type }` - - `timezone: optional string` + - `caller_id: string` - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + The call ID of the program item that produced this tool call. - - `type: optional "approximate"` + - `type: "program"` - The type of location approximation. Always `approximate`. + - `"program"` - - `"approximate"` + - `namespace: optional string` - - `Mcp object { server_label, type, allowed_callers, 9 more }` + The namespace of the custom tool being called. - Give the model access to additional tools via remote Model Context Protocol - (MCP) servers. [Learn more about MCP](/docs/guides/tools-remote-mcp). + - `CustomToolCallOutput object { call_id, output, type, 2 more }` - - `server_label: string` + The output of a custom tool call from your code, being sent back to the model. - A label for this MCP server, used to identify it in tool calls. + - `call_id: string` - - `type: "mcp"` + The call ID, used to map this custom tool call output to a custom tool call. - The type of the MCP tool. Always `mcp`. + - `output: string or array of ResponseInputText or ResponseInputImage or ResponseInputFile` - - `"mcp"` + The output from the custom tool call generated by your code. + Can be a string or an list of output content. - - `allowed_callers: optional array of "direct" or "programmatic"` + - `StringOutput = string` - The tool invocation context(s). + A string of the output of the custom tool call. - - `"direct"` + - `OutputContentList = array of ResponseInputText or ResponseInputImage or ResponseInputFile` - - `"programmatic"` + Text, image, or file output of the custom tool call. - - `allowed_tools: optional array of string or object { read_only, tool_names }` + - `ResponseInputText object { text, type, prompt_cache_breakpoint }` - List of allowed tool names or a filter object. + A text input to the model. - - `McpAllowedTools = array of string` + - `ResponseInputImage object { detail, type, file_id, 2 more }` - A string array of allowed tool names + An image input to the model. Learn about [image inputs](/docs/guides/vision). - - `McpToolFilter object { read_only, tool_names }` + - `ResponseInputFile object { type, detail, file_data, 4 more }` - A filter object to specify which tools are allowed. + A file input to the model. - - `read_only: optional boolean` + - `type: "custom_tool_call_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. + The type of the custom tool call output. Always `custom_tool_call_output`. - - `tool_names: optional array of string` + - `"custom_tool_call_output"` - List of allowed tool names. + - `id: optional string` - - `authorization: optional string` + The unique ID of the custom tool call output in the OpenAI platform. - 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. + - `caller: optional object { type } or object { caller_id, type }` - - `connector_id: optional "connector_dropbox" or "connector_gmail" or "connector_googlecalendar" or 5 more` + The execution context that produced this tool call. - Identifier for service connectors, like those available in ChatGPT. One of - `server_url`, `connector_id`, or `tunnel_id` must be provided. Learn more - about service connectors [here](/docs/guides/tools-remote-mcp#connectors). + - `Direct object { type }` - Currently supported `connector_id` values are: + - `type: "direct"` - - 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 caller type. Always `direct`. - - `"connector_dropbox"` + - `"direct"` - - `"connector_gmail"` + - `Program object { caller_id, type }` - - `"connector_googlecalendar"` + - `caller_id: string` - - `"connector_googledrive"` + The call ID of the program item that produced this tool call. - - `"connector_microsoftteams"` + - `type: "program"` - - `"connector_outlookcalendar"` + The caller type. Always `program`. - - `"connector_outlookemail"` + - `"program"` - - `"connector_sharepoint"` + - `usage: ResponseUsage` - - `defer_loading: optional boolean` + Token accounting for the compaction pass, including cached, reasoning, and total tokens. - Whether this MCP tool is deferred and discovered via tool search. + - `input_tokens: number` - - `headers: optional map[string]` + The number of input tokens. - Optional HTTP headers to send to the MCP server. Use for authentication - or other purposes. + - `input_tokens_details: object { cache_write_tokens, cached_tokens }` - - `require_approval: optional object { always, never } or "always" or "never"` + A detailed breakdown of the input tokens. - Specify which of the MCP server's tools require approval. + - `cache_write_tokens: number` - - `McpToolApprovalFilter object { always, never }` + The number of input tokens that were written to the cache. - Specify which of the MCP server's tools require approval. Can be - `always`, `never`, or a filter object associated with tools - that require approval. + - `cached_tokens: number` - - `always: optional object { read_only, tool_names }` + The number of tokens that were retrieved from the cache. + [More on prompt caching](/docs/guides/prompt-caching). - A filter object to specify which tools are allowed. + - `output_tokens: number` - - `read_only: optional boolean` + The number of output tokens. - Indicates whether or not a tool modifies data or is read-only. If an - MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), - it will match this filter. + - `output_tokens_details: object { reasoning_tokens }` - - `tool_names: optional array of string` + A detailed breakdown of the output tokens. - List of allowed tool names. + - `reasoning_tokens: number` - - `never: optional object { read_only, tool_names }` + The number of reasoning tokens. - A filter object to specify which tools are allowed. + - `total_tokens: number` - - `read_only: optional boolean` + The total number of tokens used. - 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. +### Example - - `tool_names: optional array of string` +```http +curl https://api.openai.com/v1/responses/compact \ + -H 'Content-Type: application/json' \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -d '{ + "model": "gpt-5.6-sol", + "previous_response_id": "resp_123" + }' +``` - List of allowed tool names. +#### Response - - `McpToolApprovalSetting = "always" or "never"` +```json +{ + "id": "id", + "created_at": 0, + "object": "response.compaction", + "output": [ + { + "id": "id", + "content": [ + { + "text": "text", + "type": "input_text", + "prompt_cache_breakpoint": { + "mode": "explicit" + } + } + ], + "role": "unknown", + "status": "in_progress", + "type": "message", + "phase": "commentary" + } + ], + "usage": { + "input_tokens": 0, + "input_tokens_details": { + "cache_write_tokens": 0, + "cached_tokens": 0 + }, + "output_tokens": 0, + "output_tokens_details": { + "reasoning_tokens": 0 + }, + "total_tokens": 0 + } +} +``` - 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. +### Example - - `"always"` +```http +curl -X POST https://api.openai.com/v1/responses/compact \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -d '{ + "model": "gpt-5.1-codex-max", + "input": [ + { + "role": "user", + "content": "Create a simple landing page for a dog petting café." + }, + { + "id": "msg_001", + "type": "message", + "status": "completed", + "content": [ + { + "type": "output_text", + "annotations": [], + "logprobs": [], + "text": "Below is a single file, ready-to-use landing page for a dog petting café:..." + } + ], + "role": "assistant" + } + ] + }' +``` - - `"never"` +#### Response - - `server_description: optional string` +```json +{ + "id": "resp_001", + "object": "response.compaction", + "created_at": 1764967971, + "output": [ + { + "id": "msg_000", + "type": "message", + "status": "completed", + "content": [ + { + "type": "input_text", + "text": "Create a simple landing page for a dog petting cafe." + } + ], + "role": "user" + }, + { + "id": "cmp_001", + "type": "compaction", + "encrypted_content": "gAAAAABpM0Yj-...=" + } + ], + "usage": { + "input_tokens": 139, + "input_tokens_details": { + "cached_tokens": 0, + "cache_write_tokens": 0 + }, + "output_tokens": 438, + "output_tokens_details": { + "reasoning_tokens": 64 + }, + "total_tokens": 577 + } +} +``` - Optional description of the MCP server, used to provide more context. +## Create a model response - - `server_url: optional string` +**post** `/responses` - The URL for the MCP server. One of `server_url`, `connector_id`, or - `tunnel_id` must be provided. +Creates a model response. Provide [text](/docs/guides/text) or +[image](/docs/guides/images) inputs to generate [text](/docs/guides/text) +or [JSON](/docs/guides/structured-outputs) outputs. Have the model call +your own [custom code](/docs/guides/function-calling) or use built-in +[tools](/docs/guides/tools) like [web search](/docs/guides/tools-web-search) +or [file search](/docs/guides/tools-file-search) to use your own data +as input for the model's response. - - `tunnel_id: optional string` +### Body Parameters - The Secure MCP Tunnel ID to use instead of a direct server URL. One of - `server_url`, `connector_id`, or `tunnel_id` must be provided. +- `background: optional boolean` - - `CodeInterpreter object { container, type, allowed_callers }` + Whether to run the model response in the background. + [Learn more](/docs/guides/background). - A tool that runs Python code to help generate a response to a prompt. +- `context_management: optional array of object { type, compact_threshold }` - - `container: string or object { type, file_ids, memory_limit, network_policy }` + Context management configuration for this request. - The code interpreter container. Can be a container ID or an object that - specifies uploaded file IDs to make available to your code, along with an - optional `memory_limit` setting. + - `type: string` - - `string` + The context management entry type. Currently only 'compaction' is supported. - The container ID. + - `compact_threshold: optional number` - - `CodeInterpreterToolAuto object { type, file_ids, memory_limit, network_policy }` + Token threshold at which compaction should be triggered for this entry. - Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. +- `conversation: optional string or ResponseConversationParam` - - `type: "auto"` + The conversation that this response belongs to. Items from this conversation are prepended to `input_items` for this response request. + Input items and output items from this response are automatically added to this conversation after this response completes. - Always `auto`. + - `ConversationID = string` - - `"auto"` + The unique ID of the conversation. - - `file_ids: optional array of string` + - `ResponseConversationParam object { id }` - An optional list of uploaded files to make available to your code. + The conversation that this response belongs to. - - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` + - `id: string` - The memory limit for the code interpreter container. + The unique ID of the conversation. - - `"1g"` +- `include: optional array of ResponseIncludable` - - `"4g"` + Specify additional output data to include in the model response. Currently supported values are: - - `"16g"` + - `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). - - `"64g"` + - `"file_search_call.results"` - - `network_policy: optional ContainerNetworkPolicyDisabled or ContainerNetworkPolicyAllowlist` + - `"web_search_call.results"` - Network access policy for the container. + - `"web_search_call.action.sources"` - - `ContainerNetworkPolicyDisabled object { type }` + - `"message.input_image.image_url"` - - `ContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` + - `"computer_call_output.output.image_url"` - - `type: "code_interpreter"` + - `"code_interpreter_call.outputs"` - The type of the code interpreter tool. Always `code_interpreter`. + - `"reasoning.encrypted_content"` - - `"code_interpreter"` + - `"message.output_text.logprobs"` - - `allowed_callers: optional array of "direct" or "programmatic"` +- `input: optional string or array of EasyInputMessage or object { content, role, status, type } or ResponseOutputMessage or 29 more` - The tool invocation context(s). + Text, image, or file inputs to the model, used to generate a response. - - `"direct"` + Learn more: - - `"programmatic"` + - [Text inputs and outputs](/docs/guides/text) + - [Image inputs](/docs/guides/images) + - [File inputs](/docs/guides/pdf-files) + - [Conversation state](/docs/guides/conversation-state) + - [Function calling](/docs/guides/function-calling) - - `ProgrammaticToolCalling object { type }` + - `TextInput = string` - - `type: "programmatic_tool_calling"` + A text input to the model, equivalent to a text input with the + `user` role. - The type of the tool. Always `programmatic_tool_calling`. + - `InputItemList = array of EasyInputMessage or object { content, role, status, type } or ResponseOutputMessage or 29 more` - - `"programmatic_tool_calling"` + A list of one or many input items to the model, containing + different content types. - - `ImageGeneration object { type, action, background, 9 more }` + - `EasyInputMessage object { content, role, phase, type }` - A tool that generates images using the GPT image models. + 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. - - `type: "image_generation"` + - `content: string or ResponseInputMessageContentList` - The type of the image generation tool. Always `image_generation`. + Text, image, or audio input to the model, used to generate a response. + Can also contain previous assistant responses. - - `"image_generation"` + - `TextInput = string` - - `action: optional "generate" or "edit" or "auto"` + A text input to the model. - Whether to generate a new image or edit an existing image. Default: `auto`. + - `ResponseInputMessageContentList = array of ResponseInputContent` - - `"generate"` + A list of one or many input items to the model, containing different content + types. - - `"edit"` + - `ResponseInputText object { text, type, prompt_cache_breakpoint }` - - `"auto"` + A text input to the model. - - `background: optional "transparent" or "opaque" or "auto"` + - `text: string` - Background type for the generated image. One of `transparent`, - `opaque`, or `auto`. Default: `auto`. + The text input to the model. - - `"transparent"` + - `type: "input_text"` - - `"opaque"` + The type of the input item. Always `input_text`. - - `"auto"` + - `"input_text"` - - `input_fidelity: optional "high" or "low"` + - `prompt_cache_breakpoint: optional object { mode }` - 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`. + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - `"high"` + - `mode: "explicit"` + + The breakpoint mode. Always `explicit`. + + - `"explicit"` + + - `ResponseInputImage object { detail, type, file_id, 2 more }` + + An image input to the model. Learn about [image inputs](/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"` - - `input_image_mask: optional object { file_id, image_url }` + - `"high"` - Optional mask for inpainting. Contains `image_url` - (string, optional) and `file_id` (string, optional). + - `"auto"` + + - `"original"` + + - `type: "input_image"` + + The type of the input item. Always `input_image`. + + - `"input_image"` - `file_id: optional string` - File ID for the mask image. + The ID of the file to be sent to the model. - `image_url: optional string` - Base64-encoded mask image. + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` + - `prompt_cache_breakpoint: optional object { mode }` - The image generation model to use. Default: `gpt-image-1`. + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - `string` + - `mode: "explicit"` - - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` + The breakpoint mode. Always `explicit`. - The image generation model to use. Default: `gpt-image-1`. + - `"explicit"` - - `"gpt-image-1"` + - `ResponseInputFile object { type, detail, file_data, 4 more }` - - `"gpt-image-1-mini"` + A file input to the model. - - `"gpt-image-1.5"` + - `type: "input_file"` - - `moderation: optional "auto" or "low"` + The type of the input item. Always `input_file`. - Moderation level for the generated image. Default: `auto`. + - `"input_file"` + + - `detail: optional "auto" or "low" or "high"` + + The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. - `"auto"` - `"low"` - - `output_compression: optional number` + - `"high"` - Compression level for the output image. Default: 100. + - `file_data: optional string` - - `output_format: optional "png" or "webp" or "jpeg"` + The content of the file to be sent to the model. - The output format of the generated image. One of `png`, `webp`, or - `jpeg`. Default: `png`. + - `file_id: optional string` - - `"png"` + The ID of the file to be sent to the model. - - `"webp"` + - `file_url: optional string` - - `"jpeg"` + The URL of the file to be sent to the model. - - `partial_images: optional number` + - `filename: optional string` - Number of partial images to generate in streaming mode, from 0 (default value) to 3. + The name of the file to be sent to the model. - - `quality: optional "low" or "medium" or "high" or "auto"` + - `prompt_cache_breakpoint: optional object { mode }` - The quality of the generated image. One of `low`, `medium`, `high`, - or `auto`. Default: `auto`. + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - `"low"` + - `mode: "explicit"` - - `"medium"` + The breakpoint mode. Always `explicit`. - - `"high"` + - `"explicit"` - - `"auto"` + - `role: "user" or "assistant" or "system" or "developer"` - - `size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or "auto"` + The role of the message input. One of `user`, `assistant`, `system`, or + `developer`. - 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"` - - `string` + - `"assistant"` - - `"1024x1024" or "1024x1536" or "1536x1024" or "auto"` + - `"system"` - 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`. + - `"developer"` - - `"1024x1024"` + - `phase: optional "commentary" or "final_answer"` - - `"1024x1536"` + 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. - - `"1536x1024"` + - `"commentary"` - - `"auto"` + - `"final_answer"` - - `LocalShell object { type }` + - `type: optional "message"` - A tool that allows the model to execute shell commands in a local environment. + The type of the message input. Always `message`. - - `type: "local_shell"` + - `"message"` - The type of the local shell tool. Always `local_shell`. + - `Message object { content, role, status, type }` - - `"local_shell"` + 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. - - `Shell object { type, allowed_callers, environment }` + - `content: ResponseInputMessageContentList` - A tool that allows the model to execute shell commands. + A list of one or many input items to the model, containing different content + types. - - `type: "shell"` + - `role: "user" or "system" or "developer"` - The type of the shell tool. Always `shell`. + The role of the message input. One of `user`, `system`, or `developer`. - - `"shell"` + - `"user"` - - `allowed_callers: optional array of "direct" or "programmatic"` + - `"system"` - The tool invocation context(s). + - `"developer"` - - `"direct"` + - `status: optional "in_progress" or "completed" or "incomplete"` - - `"programmatic"` + The status of item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `environment: optional ContainerAuto or LocalEnvironment or ContainerReference` + - `"in_progress"` - - `ContainerAuto object { type, file_ids, memory_limit, 2 more }` + - `"completed"` - - `LocalEnvironment object { type, skills }` + - `"incomplete"` - - `ContainerReference object { container_id, type }` + - `type: optional "message"` - - `Custom object { name, type, allowed_callers, 3 more }` + The type of the message input. Always set to `message`. - A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) + - `"message"` - - `name: string` + - `ResponseOutputMessage object { id, content, role, 3 more }` - The name of the custom tool, used to identify it in tool calls. + An output message from the model. - - `type: "custom"` + - `id: string` - The type of the custom tool. Always `custom`. + The unique ID of the output message. - - `"custom"` + - `content: array of ResponseOutputText or ResponseOutputRefusal` - - `allowed_callers: optional array of "direct" or "programmatic"` + The content of the output message. - The tool invocation context(s). + - `ResponseOutputText object { annotations, logprobs, text, type }` - - `"direct"` + A text output from the model. - - `"programmatic"` + - `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 }` - - `defer_loading: optional boolean` + The annotations of the text output. - Whether this tool should be deferred and discovered via tool search. + - `FileCitation object { file_id, filename, index, type }` - - `description: optional string` + A citation to a file. - Optional description of the custom tool, used to provide more context. + - `file_id: string` - - `format: optional CustomToolInputFormat` + The ID of the file. - The input format for the custom tool. Default is unconstrained text. + - `filename: string` - - `Namespace object { description, name, tools, type }` + The filename of the file cited. - Groups function/custom tools under a shared namespace. + - `index: number` - - `description: string` + The index of the file in the list of files. - A description of the namespace shown to the model. + - `type: "file_citation"` - - `name: string` + The type of the file citation. Always `file_citation`. - The namespace name used in tool calls (for example, `crm`). + - `"file_citation"` - - `tools: array of object { name, type, allowed_callers, 5 more } or object { name, type, allowed_callers, 3 more }` + - `URLCitation object { end_index, start_index, title, 2 more }` - The function/custom tools available inside this namespace. + A citation for a web resource used to generate a model response. - - `Function object { name, type, allowed_callers, 5 more }` + - `end_index: number` - - `name: string` + The index of the last character of the URL citation in the message. - - `type: "function"` + - `start_index: number` - - `"function"` + The index of the first character of the URL citation in the message. - - `allowed_callers: optional array of "direct" or "programmatic"` + - `title: string` - The tool invocation context(s). + The title of the web resource. - - `"direct"` + - `type: "url_citation"` - - `"programmatic"` + The type of the URL citation. Always `url_citation`. - - `defer_loading: optional boolean` + - `"url_citation"` - Whether this function should be deferred and discovered via tool search. + - `url: string` - - `description: optional string` + The URL of the web resource. - - `output_schema: optional map[unknown]` + - `ContainerFileCitation object { container_id, end_index, file_id, 3 more }` - A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. + A citation for a container file used to generate a model response. - - `parameters: optional unknown` + - `container_id: string` - - `strict: optional boolean` + The ID of the container file. - Whether to enforce strict parameter validation. If omitted, Responses attempts to use strict validation when the schema is compatible, and falls back to non-strict validation otherwise. + - `end_index: number` - - `Custom object { name, type, allowed_callers, 3 more }` + The index of the last character of the container file citation in the message. - A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) + - `file_id: string` - - `name: string` + The ID of the file. - The name of the custom tool, used to identify it in tool calls. + - `filename: string` - - `type: "custom"` + The filename of the container file cited. - The type of the custom tool. Always `custom`. + - `start_index: number` - - `"custom"` + The index of the first character of the container file citation in the message. - - `allowed_callers: optional array of "direct" or "programmatic"` + - `type: "container_file_citation"` - The tool invocation context(s). + The type of the container file citation. Always `container_file_citation`. - - `"direct"` + - `"container_file_citation"` - - `"programmatic"` + - `FilePath object { file_id, index, type }` - - `defer_loading: optional boolean` + A path to a file. - Whether this tool should be deferred and discovered via tool search. + - `file_id: string` - - `description: optional string` + The ID of the file. - Optional description of the custom tool, used to provide more context. + - `index: number` - - `format: optional CustomToolInputFormat` + The index of the file in the list of files. - The input format for the custom tool. Default is unconstrained text. + - `type: "file_path"` - - `type: "namespace"` + The type of the file path. Always `file_path`. - The type of the tool. Always `namespace`. + - `"file_path"` - - `"namespace"` + - `logprobs: array of object { token, bytes, logprob, top_logprobs }` - - `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`. + - `top_logprobs: array of object { token, bytes, logprob }` - - `"tool_search"` + - `token: string` - - `description: optional string` + - `bytes: array of number` - Description shown to the model for a client-executed tool search tool. + - `logprob: number` - - `execution: optional "server" or "client"` + - `text: string` - Whether tool search is executed by the server or by the client. + The text output from the model. - - `"server"` + - `type: "output_text"` - - `"client"` + The type of the output text. Always `output_text`. - - `parameters: optional unknown` + - `"output_text"` - Parameter schema for a client-executed tool search tool. + - `ResponseOutputRefusal object { refusal, type }` - - `WebSearchPreview object { type, search_content_types, search_context_size, user_location }` + A refusal from 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). + - `refusal: string` - - `type: "web_search_preview" or "web_search_preview_2025_03_11"` + The refusal explanation from the model. - The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. + - `type: "refusal"` - - `"web_search_preview"` + The type of the refusal. Always `refusal`. - - `"web_search_preview_2025_03_11"` + - `"refusal"` - - `search_content_types: optional array of "text" or "image"` + - `role: "assistant"` - - `"text"` + The role of the output message. Always `assistant`. - - `"image"` + - `"assistant"` - - `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 message input. One of `in_progress`, `completed`, or + `incomplete`. Populated when input items are returned via API. - - `"low"` + - `"in_progress"` - - `"medium"` + - `"completed"` - - `"high"` + - `"incomplete"` - - `user_location: optional object { type, city, country, 2 more }` + - `type: "message"` - The user's location. + The type of the output message. Always `message`. - - `type: "approximate"` + - `"message"` - The type of location approximation. Always `approximate`. + - `phase: optional "commentary" or "final_answer"` - - `"approximate"` + 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. - - `city: optional string` + - `"commentary"` - Free text input for the city of the user, e.g. `San Francisco`. + - `"final_answer"` - - `country: optional string` + - `FileSearchCall object { id, queries, status, 2 more }` - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + The results of a file search tool call. See the + [file search guide](/docs/guides/tools-file-search) for more information. - - `region: optional string` + - `id: string` - Free text input for the region of the user, e.g. `California`. + The unique ID of the file search tool call. - - `timezone: optional string` + - `queries: array of string` - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + The queries used to search for files. - - `ApplyPatch object { type, allowed_callers }` + - `status: "in_progress" or "searching" or "completed" or 2 more` - Allows the assistant to create, delete, or update files using unified diffs. + The status of the file search tool call. One of `in_progress`, + `searching`, `incomplete` or `failed`, - - `type: "apply_patch"` + - `"in_progress"` - The type of the tool. Always `apply_patch`. + - `"searching"` - - `"apply_patch"` + - `"completed"` - - `allowed_callers: optional array of "direct" or "programmatic"` + - `"incomplete"` - The tool invocation context(s). + - `"failed"` - - `"direct"` + - `type: "file_search_call"` - - `"programmatic"` + The type of the file search tool call. Always `file_search_call`. - - `type: "additional_tools"` + - `"file_search_call"` - The item type. Always `additional_tools`. + - `results: optional array of object { attributes, file_id, filename, 2 more }` - - `"additional_tools"` + The results of the file search tool call. - - `id: optional string` + - `attributes: optional map[string or number or boolean]` - The unique ID of this additional tools item. + 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. - - `Reasoning object { id, summary, type, 3 more }` + - `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). + - `number` - - `id: string` + - `boolean` - The unique identifier of the reasoning content. + - `file_id: optional string` - - `summary: array of SummaryTextContent` + The unique ID of the file. - Reasoning summary content. + - `filename: optional string` - - `text: string` + The name of the file. - A summary of the reasoning output from the model so far. + - `score: optional number` - - `type: "summary_text"` + The relevance score of the file - a value between 0 and 1. - The type of the object. Always `summary_text`. + - `text: optional string` - - `"summary_text"` + The text that was retrieved from the file. - - `type: "reasoning"` + - `ComputerCall object { id, call_id, pending_safety_checks, 4 more }` - The type of the object. Always `reasoning`. + A tool call to a computer use tool. See the + [computer use guide](/docs/guides/tools-computer-use) for more information. - - `"reasoning"` + - `id: string` - - `content: optional array of object { text, type }` + The unique ID of the computer call. - Reasoning text content. + - `call_id: string` - - `text: string` + An identifier used when responding to the tool call with output. - The reasoning text from the model. + - `pending_safety_checks: array of object { id, code, message }` - - `type: "reasoning_text"` + The pending safety checks for the computer call. - The type of the reasoning text. Always `reasoning_text`. + - `id: string` - - `"reasoning_text"` + The ID of the pending safety check. - - `encrypted_content: optional string` + - `code: optional string` - The encrypted content of the reasoning item. This is populated by default - for reasoning items returned by `POST /v1/responses` and WebSocket - `response.create` requests. + The type of the pending safety check. - - `status: optional "in_progress" or "completed" or "incomplete"` + - `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. @@ -19011,278 +18299,304 @@ Retrieves a model response with the given ID. - `"incomplete"` - - `Compaction object { encrypted_content, type, id }` + - `type: "computer_call"` - A compaction item generated by the [`v1/responses/compact` API](/docs/api-reference/responses/compact). + The type of the computer call. Always `computer_call`. - - `encrypted_content: string` + - `"computer_call"` - The encrypted content of the compaction summary. + - `action: optional ComputerAction` - - `type: "compaction"` + A click action. - The type of the item. Always `compaction`. + - `Click object { button, type, x, 2 more }` - - `"compaction"` + A click action. - - `id: optional string` + - `button: "left" or "right" or "wheel" or 2 more` - The ID of the compaction item. + Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. - - `ImageGenerationCall object { id, result, status, type }` + - `"left"` - An image generation request made by the model. + - `"right"` - - `id: string` + - `"wheel"` - The unique ID of the image generation call. + - `"back"` - - `result: string` + - `"forward"` - The generated image encoded in base64. + - `type: "click"` - - `status: "in_progress" or "completed" or "generating" or "failed"` + Specifies the event type. For a click action, this property is always `click`. - The status of the image generation call. + - `"click"` - - `"in_progress"` + - `x: number` - - `"completed"` + The x-coordinate where the click occurred. - - `"generating"` + - `y: number` - - `"failed"` + The y-coordinate where the click occurred. - - `type: "image_generation_call"` + - `keys: optional array of string` - The type of the image generation call. Always `image_generation_call`. + The keys being held while clicking. - - `"image_generation_call"` + - `DoubleClick object { keys, type, x, y }` - - `CodeInterpreterCall object { id, code, container_id, 3 more }` + A double click action. - A tool call to run code. + - `keys: array of string` - - `id: string` + The keys being held while double-clicking. - The unique ID of the code interpreter tool call. + - `type: "double_click"` - - `code: string` + Specifies the event type. For a double click action, this property is always set to `double_click`. - The code to run, or null if not available. + - `"double_click"` - - `container_id: string` + - `x: number` - The ID of the container used to run the code. + The x-coordinate where the double click occurred. - - `outputs: array of object { logs, type } or object { type, url }` + - `y: number` - The outputs generated by the code interpreter, such as logs or images. - Can be null if no outputs are available. + The y-coordinate where the double click occurred. - - `Logs object { logs, type }` + - `Drag object { path, type, keys }` - The logs output from the code interpreter. + A drag action. - - `logs: string` + - `path: array of object { x, y }` - The logs output from the code interpreter. + An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg - - `type: "logs"` + ``` + [ + { x: 100, y: 200 }, + { x: 200, y: 300 } + ] + ``` - The type of the output. Always `logs`. + - `x: number` - - `"logs"` + The x-coordinate. - - `Image object { type, url }` + - `y: number` - The image output from the code interpreter. + The y-coordinate. - - `type: "image"` + - `type: "drag"` - The type of the output. Always `image`. + Specifies the event type. For a drag action, this property is always set to `drag`. - - `"image"` + - `"drag"` - - `url: string` + - `keys: optional array of string` - The URL of the image output from the code interpreter. + The keys being held while dragging the mouse. - - `status: "in_progress" or "completed" or "incomplete" or 2 more` + - `Keypress object { keys, type }` - The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. + A collection of keypresses the model would like to perform. - - `"in_progress"` + - `keys: array of string` - - `"completed"` + The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. - - `"incomplete"` + - `type: "keypress"` - - `"interpreting"` + Specifies the event type. For a keypress action, this property is always set to `keypress`. - - `"failed"` + - `"keypress"` - - `type: "code_interpreter_call"` + - `Move object { type, x, y, keys }` - The type of the code interpreter tool call. Always `code_interpreter_call`. + A mouse move action. - - `"code_interpreter_call"` + - `type: "move"` - - `LocalShellCall object { id, action, call_id, 2 more }` + Specifies the event type. For a move action, this property is always set to `move`. - A tool call to run a command on the local shell. + - `"move"` - - `id: string` + - `x: number` - The unique ID of the local shell call. + The x-coordinate to move to. - - `action: object { command, env, type, 3 more }` + - `y: number` - Execute a shell command on the server. + The y-coordinate to move to. - - `command: array of string` + - `keys: optional array of string` - The command to run. + The keys being held while moving the mouse. - - `env: map[string]` + - `Screenshot object { type }` - Environment variables to set for the command. + A screenshot action. - - `type: "exec"` + - `type: "screenshot"` - The type of the local shell action. Always `exec`. + Specifies the event type. For a screenshot action, this property is always set to `screenshot`. - - `"exec"` + - `"screenshot"` - - `timeout_ms: optional number` + - `Scroll object { scroll_x, scroll_y, type, 3 more }` - Optional timeout in milliseconds for the command. + A scroll action. - - `user: optional string` + - `scroll_x: number` - Optional user to run the command as. + The horizontal scroll distance. - - `working_directory: optional string` + - `scroll_y: number` - Optional working directory to run the command in. + The vertical scroll distance. - - `call_id: string` + - `type: "scroll"` - The unique ID of the local shell tool call generated by the model. + Specifies the event type. For a scroll action, this property is always set to `scroll`. - - `status: "in_progress" or "completed" or "incomplete"` + - `"scroll"` - The status of the local shell call. + - `x: number` - - `"in_progress"` + The x-coordinate where the scroll occurred. - - `"completed"` + - `y: number` - - `"incomplete"` + The y-coordinate where the scroll occurred. - - `type: "local_shell_call"` + - `keys: optional array of string` - The type of the local shell call. Always `local_shell_call`. + The keys being held while scrolling. - - `"local_shell_call"` + - `Type object { text, type }` - - `LocalShellCallOutput object { id, output, type, status }` + An action to type in text. - The output of a local shell tool call. + - `text: string` - - `id: string` + The text to type. - The unique ID of the local shell tool call generated by the model. + - `type: "type"` - - `output: string` + Specifies the event type. For a type action, this property is always set to `type`. - A JSON string of the output of the local shell tool call. + - `"type"` - - `type: "local_shell_call_output"` + - `Wait object { type }` - The type of the local shell tool call output. Always `local_shell_call_output`. + A wait action. - - `"local_shell_call_output"` + - `type: "wait"` - - `status: optional "in_progress" or "completed" or "incomplete"` + Specifies the event type. For a wait action, this property is always set to `wait`. - The status of the item. One of `in_progress`, `completed`, or `incomplete`. + - `"wait"` - - `"in_progress"` + - `actions: optional ComputerActionList` - - `"completed"` + Flattened batched actions for `computer_use`. Each action includes an + `type` discriminator and action-specific fields. - - `"incomplete"` + - `Click object { button, type, x, 2 more }` - - `ShellCall object { action, call_id, type, 4 more }` + A click action. - A tool representing a request to execute one or more shell commands. + - `DoubleClick object { keys, type, x, y }` - - `action: object { commands, max_output_length, timeout_ms }` + A double click action. - The shell commands and limits that describe how to run the tool call. + - `Drag object { path, type, keys }` - - `commands: array of string` + A drag action. - Ordered shell commands for the execution environment to run. + - `Keypress object { keys, type }` - - `max_output_length: optional number` + A collection of keypresses the model would like to perform. - Maximum number of UTF-8 characters to capture from combined stdout and stderr output. + - `Move object { type, x, y, keys }` - - `timeout_ms: optional number` + A mouse move action. - Maximum wall-clock time in milliseconds to allow the shell commands to run. + - `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 unique ID of the shell tool call generated by the model. + The ID of the computer tool call that produced the output. - - `type: "shell_call"` + - `output: ResponseComputerToolCallOutputScreenshot` - The type of the item. Always `shell_call`. + A computer screenshot image used with the computer use tool. - - `"shell_call"` + - `type: "computer_screenshot"` - - `id: optional string` + Specifies the event type. For a computer screenshot, this property is + always set to `computer_screenshot`. - The unique ID of the shell tool call. Populated when this item is returned via API. + - `"computer_screenshot"` - - `caller: optional object { type } or object { caller_id, type }` + - `file_id: optional string` - The execution context that produced this tool call. + The identifier of an uploaded file that contains the screenshot. - - `Direct object { type }` + - `image_url: optional string` - - `type: "direct"` + The URL of the screenshot image. - The caller type. Always `direct`. + - `type: "computer_call_output"` - - `"direct"` + The type of the computer tool call output. Always `computer_call_output`. - - `Program object { caller_id, type }` + - `"computer_call_output"` - - `caller_id: string` + - `id: optional string` - The call ID of the program item that produced this tool call. + The ID of the computer tool call output. - - `type: "program"` + - `acknowledged_safety_checks: optional array of object { id, code, message }` - The caller type. Always `program`. + The safety checks reported by the API that have been acknowledged by the developer. - - `"program"` + - `id: string` - - `environment: optional LocalEnvironment or ContainerReference` + The ID of the pending safety check. - The environment to execute the shell commands in. + - `code: optional string` - - `LocalEnvironment object { type, skills }` + The type of the pending safety check. - - `ContainerReference object { container_id, type }` + - `message: optional string` + + Details about the pending safety check. - `status: optional "in_progress" or "completed" or "incomplete"` - The status of the shell call. One of `in_progress`, `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"` @@ -19290,63 +18604,128 @@ Retrieves a model response with the given ID. - `"incomplete"` - - `ShellCallOutput object { call_id, output, type, 4 more }` + - `WebSearchCall object { id, action, status, type }` - The streamed output items emitted by a shell tool call. + The results of a web search tool call. See the + [web search guide](/docs/guides/tools-web-search) for more information. - - `call_id: string` + - `id: string` - The unique ID of the shell tool call generated by the model. + The unique ID of the web search tool call. - - `output: array of ResponseFunctionShellCallOutputContent` + - `action: object { type, queries, query, sources } or object { type, url } or object { pattern, type, url }` - Captured chunks of stdout and stderr output, along with their associated outcomes. + 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). - - `outcome: object { type } or object { exit_code, type }` + - `Search object { type, queries, query, sources }` - The exit or timeout outcome associated with this shell call. + Action type "search" - Performs a web search query. - - `Timeout object { type }` + - `type: "search"` - Indicates that the shell call exceeded its configured time limit. + The action type. - - `type: "timeout"` + - `"search"` - The outcome type. Always `timeout`. + - `queries: optional array of string` - - `"timeout"` + The search queries. - - `Exit object { exit_code, type }` + - `query: optional string` - Indicates that the shell commands finished and returned an exit code. + The search query. - - `exit_code: number` + - `sources: optional array of object { type, url }` - The exit code returned by the shell process. + The sources used in the search. - - `type: "exit"` + - `type: "url"` - The outcome type. Always `exit`. + The type of source. Always `url`. - - `"exit"` + - `"url"` - - `stderr: string` + - `url: string` - Captured stderr output for the shell call. + The URL of the source. - - `stdout: string` + - `OpenPage object { type, url }` - Captured stdout output for the shell call. + Action type "open_page" - Opens a specific URL from search results. - - `type: "shell_call_output"` + - `type: "open_page"` - The type of the item. Always `shell_call_output`. + The action type. - - `"shell_call_output"` + - `"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, 5 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 shell tool call output. Populated when this item is returned via API. + The unique ID of the function tool call. - `caller: optional object { type } or object { caller_id, type }` @@ -19356,8 +18735,6 @@ Retrieves a model response with the given ID. - `type: "direct"` - The caller type. Always `direct`. - - `"direct"` - `Program object { caller_id, type }` @@ -19368,17 +18745,16 @@ Retrieves a model response with the given ID. - `type: "program"` - The caller type. Always `program`. - - `"program"` - - `max_output_length: optional number` + - `namespace: optional string` - The maximum number of UTF-8 characters captured for this shell call's combined output. + The namespace of the function to run. - `status: optional "in_progress" or "completed" or "incomplete"` - The status of the shell call output. + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - `"in_progress"` @@ -19386,135 +18762,145 @@ Retrieves a model response with the given ID. - `"incomplete"` - - `ApplyPatchCall object { call_id, operation, status, 3 more }` + - `FunctionCallOutput object { call_id, output, type, 3 more }` - A tool call representing a request to create, delete, or update files using diff patches. + The output of a function tool call. - `call_id: string` - The unique ID of the apply patch tool call generated by the model. + The unique ID of the function tool call generated by the model. - - `operation: object { diff, path, type } or object { path, type } or object { diff, path, type }` + - `output: string or array of ResponseInputTextContent or ResponseInputImageContent or ResponseInputFileContent` - The specific create, delete, or update instruction for the apply_patch tool call. + Text, image, or file output of the function tool call. - - `CreateFile object { diff, path, type }` + - `string` - Instruction for creating a new file via the apply_patch tool. + A JSON string of the output of the function tool call. - - `diff: string` + - `array of ResponseInputTextContent or ResponseInputImageContent or ResponseInputFileContent` - Unified diff content to apply when creating the file. + An array of content outputs (text, image, file) for the function tool call. - - `path: string` + - `ResponseInputTextContent object { text, type, prompt_cache_breakpoint }` - Path of the file to create relative to the workspace root. + A text input to the model. - - `type: "create_file"` + - `text: string` - The operation type. Always `create_file`. + The text input to the model. - - `"create_file"` + - `type: "input_text"` - - `DeleteFile object { path, type }` + The type of the input item. Always `input_text`. - Instruction for deleting an existing file via the apply_patch tool. + - `"input_text"` - - `path: string` + - `prompt_cache_breakpoint: optional object { mode }` - Path of the file to delete relative to the workspace root. + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - `type: "delete_file"` + - `mode: "explicit"` - The operation type. Always `delete_file`. + The breakpoint mode. Always `explicit`. - - `"delete_file"` + - `"explicit"` - - `UpdateFile object { diff, path, type }` + - `ResponseInputImageContent object { type, detail, file_id, 2 more }` - Instruction for updating an existing file via the apply_patch tool. + An image input to the model. Learn about [image inputs](/docs/guides/vision) - - `diff: string` + - `type: "input_image"` - Unified diff content to apply to the existing file. + The type of the input item. Always `input_image`. - - `path: string` + - `"input_image"` - Path of the file to update relative to the workspace root. + - `detail: optional "low" or "high" or "auto" or "original"` - - `type: "update_file"` + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - The operation type. Always `update_file`. + - `"low"` - - `"update_file"` + - `"high"` - - `status: "in_progress" or "completed"` + - `"auto"` - The status of the apply patch tool call. One of `in_progress` or `completed`. + - `"original"` - - `"in_progress"` + - `file_id: optional string` - - `"completed"` + The ID of the file to be sent to the model. - - `type: "apply_patch_call"` + - `image_url: optional string` - The type of the item. Always `apply_patch_call`. + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - - `"apply_patch_call"` + - `prompt_cache_breakpoint: optional object { mode }` - - `id: optional string` + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - The unique ID of the apply patch tool call. Populated when this item is returned via API. + - `mode: "explicit"` - - `caller: optional object { type } or object { caller_id, type }` + The breakpoint mode. Always `explicit`. - The execution context that produced this tool call. + - `"explicit"` - - `Direct object { type }` + - `ResponseInputFileContent object { type, detail, file_data, 4 more }` - - `type: "direct"` + A file input to the model. - The caller type. Always `direct`. + - `type: "input_file"` - - `"direct"` + The type of the input item. Always `input_file`. - - `Program object { caller_id, type }` + - `"input_file"` - - `caller_id: string` + - `detail: optional "auto" or "low" or "high"` - The call ID of the program item that produced this tool call. + The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. - - `type: "program"` + - `"auto"` - The caller type. Always `program`. + - `"low"` - - `"program"` + - `"high"` - - `ApplyPatchCallOutput object { call_id, status, type, 3 more }` + - `file_data: optional string` - The streamed output emitted by an apply patch tool call. + The base64-encoded data of the file to be sent to the model. - - `call_id: string` + - `file_id: optional string` - The unique ID of the apply patch tool call generated by the model. + The ID of the file to be sent to the model. - - `status: "completed" or "failed"` + - `file_url: optional string` - The status of the apply patch tool call output. One of `completed` or `failed`. + The URL of the file to be sent to the model. - - `"completed"` + - `filename: optional string` - - `"failed"` + The name of the file to be sent to the model. - - `type: "apply_patch_call_output"` + - `prompt_cache_breakpoint: optional object { mode }` - The type of the item. Always `apply_patch_call_output`. + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - `"apply_patch_call_output"` + - `mode: "explicit"` + + The breakpoint mode. Always `explicit`. + + - `"explicit"` + + - `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 apply patch tool call output. Populated when this item is returned via API. + The unique ID of the function tool call output. Populated when this item is returned via API. - `caller: optional object { type } or object { caller_id, type }` @@ -19540,1125 +18926,1133 @@ Retrieves a model response with the given ID. - `"program"` - - `output: optional string` + - `status: optional "in_progress" or "completed" or "incomplete"` - Optional human-readable log text from the apply patch tool (e.g., patch results or errors). + The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. - - `McpListTools object { id, server_label, tools, 2 more }` + - `"in_progress"` - A list of tools available on an MCP server. + - `"completed"` - - `id: string` + - `"incomplete"` - The unique ID of the list. + - `ToolSearchCall object { arguments, type, id, 3 more }` - - `server_label: string` + - `arguments: unknown` - The label of the MCP server. + The arguments supplied to the tool search call. - - `tools: array of object { input_schema, name, annotations, description }` + - `type: "tool_search_call"` - The tools available on the server. + The item type. Always `tool_search_call`. - - `input_schema: unknown` + - `"tool_search_call"` - The JSON schema describing the tool's input. + - `id: optional string` - - `name: string` + The unique ID of this tool search call. - The name of the tool. + - `call_id: optional string` - - `annotations: optional unknown` + The unique ID of the tool search call generated by the model. - Additional annotations about the tool. + - `execution: optional "server" or "client"` - - `description: optional string` + Whether tool search was executed by the server or by the client. - The description of the tool. + - `"server"` - - `type: "mcp_list_tools"` + - `"client"` - The type of the item. Always `mcp_list_tools`. + - `status: optional "in_progress" or "completed" or "incomplete"` - - `"mcp_list_tools"` + The status of the tool search call. - - `error: optional string` + - `"in_progress"` - Error message if the server could not list tools. + - `"completed"` - - `McpApprovalRequest object { id, arguments, name, 2 more }` + - `"incomplete"` - A request for human approval of a tool invocation. + - `ToolSearchOutput object { tools, type, id, 3 more }` - - `id: string` + - `tools: array of object { name, parameters, strict, 5 more } or object { type, vector_store_ids, filters, 2 more } or object { type } or 13 more` - The unique ID of the approval request. + The loaded tool definitions returned by the tool search output. - - `arguments: string` + - `Function object { name, parameters, strict, 5 more }` - A JSON string of arguments for the tool. + 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 tool to run. + The name of the function to call. - - `server_label: string` + - `parameters: map[unknown]` - The label of the MCP server making the request. + A JSON schema object describing the parameters of the function. - - `type: "mcp_approval_request"` + - `strict: boolean` - The type of the item. Always `mcp_approval_request`. + Whether strict parameter validation is enforced for this function tool. - - `"mcp_approval_request"` + - `type: "function"` - - `McpApprovalResponse object { approval_request_id, approve, type, 2 more }` + The type of the function tool. Always `function`. - A response to an MCP approval request. + - `"function"` - - `approval_request_id: string` + - `allowed_callers: optional array of "direct" or "programmatic"` - The ID of the approval request being answered. + The tool invocation context(s). - - `approve: boolean` + - `"direct"` - Whether the request was approved. + - `"programmatic"` - - `type: "mcp_approval_response"` + - `defer_loading: optional boolean` - The type of the item. Always `mcp_approval_response`. + Whether this function is deferred and loaded via tool search. - - `"mcp_approval_response"` + - `description: optional string` - - `id: optional string` + A description of the function. Used by the model to determine whether or not to call the function. - The unique ID of the approval response + - `output_schema: optional map[unknown]` - - `reason: optional string` + A JSON schema object describing the JSON value encoded in string outputs for this function. - Optional reason for the decision. + - `FileSearch object { type, vector_store_ids, filters, 2 more }` - - `McpCall object { id, arguments, name, 6 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). - An invocation of a tool on an MCP server. + - `type: "file_search"` - - `id: string` + The type of the file search tool. Always `file_search`. - The unique ID of the tool call. + - `"file_search"` - - `arguments: string` + - `vector_store_ids: array of string` - A JSON string of the arguments passed to the tool. + The IDs of the vector stores to search. - - `name: string` + - `filters: optional ComparisonFilter or CompoundFilter` - The name of the tool that was run. + A filter to apply. - - `server_label: string` + - `ComparisonFilter object { key, type, value }` - The label of the MCP server running the tool. + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - - `type: "mcp_call"` + - `key: string` - The type of the item. Always `mcp_call`. + The key to compare against the value. - - `"mcp_call"` + - `type: "eq" or "ne" or "gt" or 5 more` - - `approval_request_id: optional string` + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - 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. + - `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 - - `error: optional string` + - `"eq"` - The error from the tool call, if any. + - `"ne"` - - `output: optional string` + - `"gt"` - The output from the tool call. + - `"gte"` - - `status: optional "in_progress" or "completed" or "incomplete" or 2 more` + - `"lt"` - The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. + - `"lte"` - - `"in_progress"` + - `"in"` - - `"completed"` + - `"nin"` - - `"incomplete"` + - `value: string or number or boolean or array of string or number` - - `"calling"` + The value to compare against the attribute key; supports string, number, or boolean types. - - `"failed"` + - `string` - - `CustomToolCallOutput object { call_id, output, type, 2 more }` + - `number` - The output of a custom tool call from your code, being sent back to the model. + - `boolean` - - `call_id: string` + - `array of string or number` - The call ID, used to map this custom tool call output to a custom tool call. + - `string` - - `output: string or array of ResponseInputText or ResponseInputImage or ResponseInputFile` + - `number` - The output from the custom tool call generated by your code. - Can be a string or an list of output content. + - `CompoundFilter object { filters, type }` - - `StringOutput = string` + Combine multiple filters using `and` or `or`. - A string of the output of the custom tool call. + - `filters: array of ComparisonFilter or unknown` - - `OutputContentList = array of ResponseInputText or ResponseInputImage or ResponseInputFile` + Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. - Text, image, or file output of the custom tool call. + - `ComparisonFilter object { key, type, value }` - - `ResponseInputText object { text, type, prompt_cache_breakpoint }` + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - A text input to the model. + - `unknown` - - `ResponseInputImage object { detail, type, file_id, 2 more }` + - `type: "and" or "or"` - An image input to the model. Learn about [image inputs](/docs/guides/vision). + Type of operation: `and` or `or`. - - `ResponseInputFile object { type, detail, file_data, 4 more }` + - `"and"` - A file input to the model. + - `"or"` - - `type: "custom_tool_call_output"` + - `max_num_results: optional number` - The type of the custom tool call output. Always `custom_tool_call_output`. + The maximum number of results to return. This number should be between 1 and 50 inclusive. - - `"custom_tool_call_output"` + - `ranking_options: optional object { hybrid_search, ranker, score_threshold }` - - `id: optional string` + Ranking options for search. - The unique ID of the custom tool call output in the OpenAI platform. + - `hybrid_search: optional object { embedding_weight, text_weight }` - - `caller: optional object { type } or object { caller_id, type }` + Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. - The execution context that produced this tool call. + - `embedding_weight: number` - - `Direct object { type }` + The weight of the embedding in the reciprocal ranking fusion. - - `type: "direct"` + - `text_weight: number` - The caller type. Always `direct`. + The weight of the text in the reciprocal ranking fusion. - - `"direct"` + - `ranker: optional "auto" or "default-2024-11-15"` - - `Program object { caller_id, type }` + The ranker to use for the file search. - - `caller_id: string` + - `"auto"` - The call ID of the program item that produced this tool call. + - `"default-2024-11-15"` - - `type: "program"` + - `score_threshold: optional number` - The caller type. Always `program`. + 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. - - `"program"` + - `Computer object { type }` - - `CustomToolCall object { call_id, input, name, 4 more }` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - A call to a custom tool created by the model. + - `type: "computer"` - - `call_id: string` + The type of the computer tool. Always `computer`. - An identifier used to map this custom tool call to a tool call output. + - `"computer"` - - `input: string` + - `ComputerUsePreview object { display_height, display_width, environment, type }` - The input for the custom 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). - - `name: string` + - `display_height: number` - The name of the custom tool being called. + The height of the computer display. - - `type: "custom_tool_call"` + - `display_width: number` - The type of the custom tool call. Always `custom_tool_call`. + The width of the computer display. - - `"custom_tool_call"` + - `environment: "windows" or "mac" or "linux" or 2 more` - - `id: optional string` + The type of computer environment to control. - The unique ID of the custom tool call in the OpenAI platform. + - `"windows"` - - `caller: optional object { type } or object { caller_id, type }` + - `"mac"` - The execution context that produced this tool call. + - `"linux"` - - `Direct object { type }` + - `"ubuntu"` - - `type: "direct"` + - `"browser"` - - `"direct"` + - `type: "computer_use_preview"` - - `Program object { caller_id, type }` + The type of the computer use tool. Always `computer_use_preview`. - - `caller_id: string` + - `"computer_use_preview"` - The call ID of the program item that produced this tool call. + - `WebSearch object { type, filters, search_context_size, user_location }` - - `type: "program"` + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](/docs/guides/tools-web-search). - - `"program"` + - `type: "web_search" or "web_search_2025_08_26"` - - `namespace: optional string` + The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. - The namespace of the custom tool being called. + - `"web_search"` - - `CompactionTrigger object { type }` + - `"web_search_2025_08_26"` - Compacts the current context. Must be the final input item. + - `filters: optional object { allowed_domains }` - - `type: "compaction_trigger"` + Filters for the search. - The type of the item. Always `compaction_trigger`. + - `allowed_domains: optional array of string` - - `"compaction_trigger"` + Allowed domains for the search. If not provided, all domains are allowed. + Subdomains of the provided domains are allowed as well. - - `ItemReference object { id, type }` + Example: `["pubmed.ncbi.nlm.nih.gov"]` - An internal identifier for an item to reference. + - `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 ID of the item to reference. + - `"low"` - - `type: optional "item_reference"` + - `"medium"` - The type of item to reference. Always `item_reference`. + - `"high"` - - `"item_reference"` + - `user_location: optional object { city, country, region, 2 more }` - - `Program object { id, call_id, code, 2 more }` + The approximate location of the user. - - `id: string` + - `city: optional string` - The unique ID of this program item. + Free text input for the city of the user, e.g. `San Francisco`. - - `call_id: string` + - `country: optional string` - The stable call ID of the program item. + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - - `code: string` + - `region: optional string` - The JavaScript source executed by programmatic tool calling. + Free text input for the region of the user, e.g. `California`. - - `fingerprint: string` + - `timezone: optional string` - Opaque program replay fingerprint that must be round-tripped. + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - - `type: "program"` + - `type: optional "approximate"` - The item type. Always `program`. + The type of location approximation. Always `approximate`. - - `"program"` + - `"approximate"` - - `ProgramOutput object { id, call_id, result, 2 more }` + - `Mcp object { server_label, type, allowed_callers, 9 more }` - - `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 unique ID of this program output item. + - `server_label: string` - - `call_id: string` + A label for this MCP server, used to identify it in tool calls. - The call ID of the program item. + - `type: "mcp"` - - `result: string` + The type of the MCP tool. Always `mcp`. - The result produced by the program item. + - `"mcp"` - - `status: "completed" or "incomplete"` + - `allowed_callers: optional array of "direct" or "programmatic"` - The terminal status of the program output. + The tool invocation context(s). - - `"completed"` + - `"direct"` - - `"incomplete"` + - `"programmatic"` - - `type: "program_output"` + - `allowed_tools: optional array of string or object { read_only, tool_names }` - The item type. Always `program_output`. + List of allowed tool names or a filter object. - - `"program_output"` + - `McpAllowedTools = array of string` - - `metadata: Metadata` + A string array of allowed tool names - 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. + - `McpToolFilter object { read_only, tool_names }` - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + A filter object to specify which tools are allowed. - - `model: ResponsesModel` + - `read_only: optional boolean` - Model ID used to generate the response, like `gpt-4o` or `o3`. OpenAI - offers a wide range of models with different capabilities, performance - characteristics, and price points. Refer to the [model guide](/docs/models) - to browse and compare available models. + 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. - - `string` + - `tool_names: optional array of string` - - `"gpt-5.6-sol" or "gpt-5.6-terra" or "gpt-5.6-luna" or 78 more` + List of allowed tool names. - - `"gpt-5.6-sol"` + - `authorization: optional string` - - `"gpt-5.6-terra"` + 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. - - `"gpt-5.6-luna"` + - `connector_id: optional "connector_dropbox" or "connector_gmail" or "connector_googlecalendar" or 5 more` - - `"gpt-5.4"` + Identifier for service connectors, like those available in ChatGPT. One of + `server_url`, `connector_id`, or `tunnel_id` must be provided. Learn more + about service connectors [here](/docs/guides/tools-remote-mcp#connectors). - - `"gpt-5.4-mini"` + Currently supported `connector_id` values are: - - `"gpt-5.4-nano"` + - 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` - - `"gpt-5.4-mini-2026-03-17"` + - `"connector_dropbox"` - - `"gpt-5.4-nano-2026-03-17"` + - `"connector_gmail"` - - `"gpt-5.3-chat-latest"` + - `"connector_googlecalendar"` - - `"gpt-5.2"` + - `"connector_googledrive"` - - `"gpt-5.2-2025-12-11"` + - `"connector_microsoftteams"` - - `"gpt-5.2-chat-latest"` + - `"connector_outlookcalendar"` - - `"gpt-5.2-pro"` + - `"connector_outlookemail"` - - `"gpt-5.2-pro-2025-12-11"` + - `"connector_sharepoint"` - - `"gpt-5.1"` + - `defer_loading: optional boolean` - - `"gpt-5.1-2025-11-13"` + Whether this MCP tool is deferred and discovered via tool search. - - `"gpt-5.1-codex"` + - `headers: optional map[string]` - - `"gpt-5.1-mini"` + Optional HTTP headers to send to the MCP server. Use for authentication + or other purposes. - - `"gpt-5.1-chat-latest"` + - `require_approval: optional object { always, never } or "always" or "never"` - - `"gpt-5"` + Specify which of the MCP server's tools require approval. - - `"gpt-5-mini"` + - `McpToolApprovalFilter object { always, never }` - - `"gpt-5-nano"` + Specify which of the MCP server's tools require approval. Can be + `always`, `never`, or a filter object associated with tools + that require approval. - - `"gpt-5-2025-08-07"` + - `always: optional object { read_only, tool_names }` - - `"gpt-5-mini-2025-08-07"` + A filter object to specify which tools are allowed. - - `"gpt-5-nano-2025-08-07"` + - `read_only: optional boolean` - - `"gpt-5-chat-latest"` + 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. - - `"gpt-4.1"` + - `tool_names: optional array of string` - - `"gpt-4.1-mini"` + List of allowed tool names. - - `"gpt-4.1-nano"` + - `never: optional object { read_only, tool_names }` - - `"gpt-4.1-2025-04-14"` + A filter object to specify which tools are allowed. - - `"gpt-4.1-mini-2025-04-14"` + - `read_only: optional boolean` - - `"gpt-4.1-nano-2025-04-14"` + 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. - - `"o4-mini"` + - `tool_names: optional array of string` - - `"o4-mini-2025-04-16"` + List of allowed tool names. - - `"o3"` + - `McpToolApprovalSetting = "always" or "never"` - - `"o3-2025-04-16"` + 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. - - `"o3-mini"` + - `"always"` - - `"o3-mini-2025-01-31"` + - `"never"` - - `"o1"` + - `server_description: optional string` - - `"o1-2024-12-17"` + Optional description of the MCP server, used to provide more context. - - `"o1-preview"` + - `server_url: optional string` - - `"o1-preview-2024-09-12"` + The URL for the MCP server. One of `server_url`, `connector_id`, or + `tunnel_id` must be provided. - - `"o1-mini"` + - `tunnel_id: optional string` - - `"o1-mini-2024-09-12"` + The Secure MCP Tunnel ID to use instead of a direct server URL. One of + `server_url`, `connector_id`, or `tunnel_id` must be provided. - - `"gpt-4o"` + - `CodeInterpreter object { container, type, allowed_callers }` - - `"gpt-4o-2024-11-20"` + A tool that runs Python code to help generate a response to a prompt. - - `"gpt-4o-2024-08-06"` + - `container: string or object { type, file_ids, memory_limit, network_policy }` - - `"gpt-4o-2024-05-13"` + 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. - - `"gpt-4o-audio-preview"` + - `string` - - `"gpt-4o-audio-preview-2024-10-01"` + The container ID. - - `"gpt-4o-audio-preview-2024-12-17"` + - `CodeInterpreterToolAuto object { type, file_ids, memory_limit, network_policy }` - - `"gpt-4o-audio-preview-2025-06-03"` + Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. - - `"gpt-4o-mini-audio-preview"` + - `type: "auto"` - - `"gpt-4o-mini-audio-preview-2024-12-17"` + Always `auto`. - - `"gpt-4o-search-preview"` + - `"auto"` - - `"gpt-4o-mini-search-preview"` + - `file_ids: optional array of string` - - `"gpt-4o-search-preview-2025-03-11"` + An optional list of uploaded files to make available to your code. - - `"gpt-4o-mini-search-preview-2025-03-11"` + - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` - - `"chatgpt-4o-latest"` + The memory limit for the code interpreter container. - - `"codex-mini-latest"` + - `"1g"` - - `"gpt-4o-mini"` + - `"4g"` - - `"gpt-4o-mini-2024-07-18"` + - `"16g"` - - `"gpt-4-turbo"` + - `"64g"` - - `"gpt-4-turbo-2024-04-09"` + - `network_policy: optional ContainerNetworkPolicyDisabled or ContainerNetworkPolicyAllowlist` - - `"gpt-4-0125-preview"` + Network access policy for the container. - - `"gpt-4-turbo-preview"` + - `ContainerNetworkPolicyDisabled object { type }` - - `"gpt-4-1106-preview"` + - `type: "disabled"` - - `"gpt-4-vision-preview"` + Disable outbound network access. Always `disabled`. - - `"gpt-4"` + - `"disabled"` - - `"gpt-4-0314"` + - `ContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` - - `"gpt-4-0613"` + - `allowed_domains: array of string` - - `"gpt-4-32k"` + A list of allowed domains when type is `allowlist`. - - `"gpt-4-32k-0314"` + - `type: "allowlist"` - - `"gpt-4-32k-0613"` + Allow outbound network access only to specified domains. Always `allowlist`. - - `"gpt-3.5-turbo"` + - `"allowlist"` - - `"gpt-3.5-turbo-16k"` + - `domain_secrets: optional array of ContainerNetworkPolicyDomainSecret` - - `"gpt-3.5-turbo-0301"` + Optional domain-scoped secrets for allowlisted domains. - - `"gpt-3.5-turbo-0613"` + - `domain: string` - - `"gpt-3.5-turbo-1106"` + The domain associated with the secret. - - `"gpt-3.5-turbo-0125"` + - `name: string` - - `"gpt-3.5-turbo-16k-0613"` + The name of the secret to inject for the domain. - - `ResponsesOnlyModel = "o1-pro" or "o1-pro-2025-03-19" or "o3-pro" or 11 more` + - `value: string` - - `"o1-pro"` + The secret value to inject for the domain. - - `"o1-pro-2025-03-19"` + - `type: "code_interpreter"` - - `"o3-pro"` + The type of the code interpreter tool. Always `code_interpreter`. - - `"o3-pro-2025-06-10"` + - `"code_interpreter"` - - `"o3-deep-research"` + - `allowed_callers: optional array of "direct" or "programmatic"` - - `"o3-deep-research-2025-06-26"` + The tool invocation context(s). - - `"o4-mini-deep-research"` + - `"direct"` - - `"o4-mini-deep-research-2025-06-26"` + - `"programmatic"` - - `"computer-use-preview"` + - `ProgrammaticToolCalling object { type }` - - `"computer-use-preview-2025-03-11"` + - `type: "programmatic_tool_calling"` - - `"gpt-5-codex"` + The type of the tool. Always `programmatic_tool_calling`. - - `"gpt-5-pro"` + - `"programmatic_tool_calling"` - - `"gpt-5-pro-2025-10-06"` + - `ImageGeneration object { type, action, background, 9 more }` - - `"gpt-5.1-codex-max"` + A tool that generates images using the GPT image models. - - `object: "response"` + - `type: "image_generation"` - The object type of this resource - always set to `response`. + The type of the image generation tool. Always `image_generation`. - - `"response"` + - `"image_generation"` - - `output: array of ResponseOutputItem` + - `action: optional "generate" or "edit" or "auto"` - An array of content items generated by the model. + Whether to generate a new image or edit an existing image. Default: `auto`. - - The length and order of items in the `output` array is dependent - on the model's response. - - Rather than accessing the first item in the `output` array and - assuming it's an `assistant` message with the content generated by - the model, you might consider using the `output_text` property where - supported in SDKs. + - `"generate"` - - `ResponseOutputMessage object { id, content, role, 3 more }` + - `"edit"` - An output message from the model. + - `"auto"` - - `FileSearchCall object { id, queries, status, 2 more }` + - `background: optional "transparent" or "opaque" or "auto"` - The results of a file search tool call. See the - [file search guide](/docs/guides/tools-file-search) for more information. + Background type for the generated image. One of `transparent`, + `opaque`, or `auto`. Default: `auto`. - - `id: string` + - `"transparent"` - The unique ID of the file search tool call. + - `"opaque"` - - `queries: array of string` + - `"auto"` - The queries used to search for files. + - `input_fidelity: optional "high" or "low"` - - `status: "in_progress" or "searching" or "completed" or 2 more` + Control how much effort the model will exert to match the style and features, especially facial features, of input images. This parameter is only supported for `gpt-image-1` and `gpt-image-1.5` and later models, unsupported for `gpt-image-1-mini`. Supports `high` and `low`. Defaults to `low`. - The status of the file search tool call. One of `in_progress`, - `searching`, `incomplete` or `failed`, + - `"high"` - - `"in_progress"` + - `"low"` - - `"searching"` + - `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` - - `"failed"` + File ID for the mask image. - - `type: "file_search_call"` + - `image_url: optional string` - The type of the file search tool call. Always `file_search_call`. + Base64-encoded mask image. - - `"file_search_call"` + - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` - - `results: optional array of object { attributes, file_id, filename, 2 more }` + The image generation model to use. Default: `gpt-image-1`. - The results of the file search tool call. + - `string` - - `attributes: optional map[string or number or boolean]` + - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` - 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 image generation model to use. Default: `gpt-image-1`. - - `string` + - `"gpt-image-1"` - - `number` + - `"gpt-image-1-mini"` - - `boolean` + - `"gpt-image-1.5"` - - `file_id: optional string` + - `moderation: optional "auto" or "low"` - The unique ID of the file. + Moderation level for the generated image. Default: `auto`. - - `filename: optional string` + - `"auto"` - The name of the file. + - `"low"` - - `score: optional number` + - `output_compression: optional number` - The relevance score of the file - a value between 0 and 1. + Compression level for the output image. Default: 100. - - `text: optional string` + - `output_format: optional "png" or "webp" or "jpeg"` - The text that was retrieved from the file. + The output format of the generated image. One of `png`, `webp`, or + `jpeg`. Default: `png`. - - `FunctionCall object { arguments, call_id, name, 5 more }` + - `"png"` - A tool call to run a function. See the - [function calling guide](/docs/guides/function-calling) for more information. + - `"webp"` - - `arguments: string` + - `"jpeg"` - A JSON string of the arguments to pass to the function. + - `partial_images: optional number` - - `call_id: string` + Number of partial images to generate in streaming mode, from 0 (default value) to 3. - The unique ID of the function tool call generated by the model. + - `quality: optional "low" or "medium" or "high" or "auto"` - - `name: string` + The quality of the generated image. One of `low`, `medium`, `high`, + or `auto`. Default: `auto`. - The name of the function to run. + - `"low"` - - `type: "function_call"` + - `"medium"` - The type of the function tool call. Always `function_call`. + - `"high"` - - `"function_call"` + - `"auto"` - - `id: optional string` + - `size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or "auto"` - The unique ID of the function 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`. - - `caller: optional object { type } or object { caller_id, type }` + - `string` - The execution context that produced this tool call. + - `"1024x1024" or "1024x1536" or "1536x1024" or "auto"` - - `Direct object { 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: "direct"` + - `"1024x1024"` - - `"direct"` + - `"1024x1536"` - - `Program object { caller_id, type }` + - `"1536x1024"` - - `caller_id: string` + - `"auto"` - The call ID of the program item that produced this tool call. + - `LocalShell object { type }` - - `type: "program"` + A tool that allows the model to execute shell commands in a local environment. - - `"program"` + - `type: "local_shell"` - - `namespace: optional string` + The type of the local shell tool. Always `local_shell`. - The namespace of the function to run. + - `"local_shell"` - - `status: optional "in_progress" or "completed" or "incomplete"` + - `Shell object { type, allowed_callers, environment }` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + A tool that allows the model to execute shell commands. - - `"in_progress"` + - `type: "shell"` - - `"completed"` + The type of the shell tool. Always `shell`. - - `"incomplete"` + - `"shell"` - - `FunctionCallOutput object { id, call_id, output, 4 more }` + - `allowed_callers: optional array of "direct" or "programmatic"` - - `id: string` + The tool invocation context(s). - The unique ID of the function call tool output. + - `"direct"` - - `call_id: string` + - `"programmatic"` - The unique ID of the function tool call generated by the model. + - `environment: optional ContainerAuto or LocalEnvironment or ContainerReference` - - `output: string or array of ResponseInputText or ResponseInputImage or ResponseInputFile` + - `ContainerAuto object { type, file_ids, memory_limit, 2 more }` - The output from the function call generated by your code. - Can be a string or an list of output content. + - `type: "container_auto"` - - `StringOutput = string` + Automatically creates a container for this request - A string of the output of the function call. + - `"container_auto"` - - `OutputContentList = array of ResponseInputText or ResponseInputImage or ResponseInputFile` + - `file_ids: optional array of string` - Text, image, or file output of the function call. + An optional list of uploaded files to make available to your code. - - `ResponseInputText object { text, type, prompt_cache_breakpoint }` + - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` - A text input to the model. + The memory limit for the container. - - `ResponseInputImage object { detail, type, file_id, 2 more }` + - `"1g"` - An image input to the model. Learn about [image inputs](/docs/guides/vision). + - `"4g"` - - `ResponseInputFile object { type, detail, file_data, 4 more }` + - `"16g"` - A file input to the model. + - `"64g"` - - `status: "in_progress" or "completed" or "incomplete"` + - `network_policy: optional ContainerNetworkPolicyDisabled or ContainerNetworkPolicyAllowlist` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + Network access policy for the container. - - `"in_progress"` + - `ContainerNetworkPolicyDisabled object { type }` - - `"completed"` + - `ContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` - - `"incomplete"` + - `skills: optional array of SkillReference or InlineSkill` - - `type: "function_call_output"` + An optional list of skills referenced by id or inline data. - The type of the function tool call output. Always `function_call_output`. + - `SkillReference object { skill_id, type, version }` - - `"function_call_output"` + - `skill_id: string` - - `caller: optional object { type } or object { caller_id, type }` + The ID of the referenced skill. - The execution context that produced this tool call. + - `type: "skill_reference"` - - `Direct object { type }` + References a skill created with the /v1/skills endpoint. - - `type: "direct"` + - `"skill_reference"` - The caller type. Always `direct`. + - `version: optional string` - - `"direct"` + Optional skill version. Use a positive integer or 'latest'. Omit for default. - - `Program object { caller_id, type }` + - `InlineSkill object { description, name, source, type }` - - `caller_id: string` + - `description: string` - The call ID of the program item that produced this tool call. + The description of the skill. - - `type: "program"` + - `name: string` - The caller type. Always `program`. + The name of the skill. - - `"program"` + - `source: InlineSkillSource` - - `created_by: optional string` + Inline skill payload - The identifier of the actor that created the item. + - `data: string` - - `WebSearchCall object { id, action, status, type }` + Base64-encoded skill zip bundle. - The results of a web search tool call. See the - [web search guide](/docs/guides/tools-web-search) for more information. + - `media_type: "application/zip"` - - `id: string` + The media type of the inline skill payload. Must be `application/zip`. - The unique ID of the web search tool call. + - `"application/zip"` - - `action: object { type, queries, query, sources } or object { type, url } or object { pattern, type, url }` + - `type: "base64"` - 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 inline skill source. Must be `base64`. - - `Search object { type, queries, query, sources }` + - `"base64"` - Action type "search" - Performs a web search query. + - `type: "inline"` - - `type: "search"` + Defines an inline skill for this request. - The action type. + - `"inline"` - - `"search"` + - `LocalEnvironment object { type, skills }` - - `queries: optional array of string` + - `type: "local"` - The search queries. + Use a local computer environment. - - `query: optional string` + - `"local"` - The search query. + - `skills: optional array of LocalSkill` - - `sources: optional array of object { type, url }` + An optional list of skills. - The sources used in the search. + - `description: string` - - `type: "url"` + The description of the skill. - The type of source. Always `url`. + - `name: string` - - `"url"` + The name of the skill. - - `url: string` + - `path: string` - The URL of the source. + The path to the directory containing the skill. - - `OpenPage object { type, url }` + - `ContainerReference object { container_id, type }` - Action type "open_page" - Opens a specific URL from search results. + - `container_id: string` - - `type: "open_page"` + The ID of the referenced container. - The action type. + - `type: "container_reference"` - - `"open_page"` + References a container created with the /v1/containers endpoint - - `url: optional string` + - `"container_reference"` - The URL opened by the model. + - `Custom object { name, type, allowed_callers, 3 more }` - - `FindInPage object { pattern, type, url }` + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) - Action type "find_in_page": Searches for a pattern within a loaded page. + - `name: string` - - `pattern: string` + The name of the custom tool, used to identify it in tool calls. - The pattern or text to search for within the page. + - `type: "custom"` - - `type: "find_in_page"` + The type of the custom tool. Always `custom`. - The action type. + - `"custom"` - - `"find_in_page"` + - `allowed_callers: optional array of "direct" or "programmatic"` - - `url: string` + The tool invocation context(s). - The URL of the page searched for the pattern. + - `"direct"` - - `status: "in_progress" or "searching" or "completed" or "failed"` + - `"programmatic"` - The status of the web search tool call. + - `defer_loading: optional boolean` - - `"in_progress"` + Whether this tool should be deferred and discovered via tool search. - - `"searching"` + - `description: optional string` - - `"completed"` + Optional description of the custom tool, used to provide more context. - - `"failed"` + - `format: optional CustomToolInputFormat` - - `type: "web_search_call"` + The input format for the custom tool. Default is unconstrained text. - The type of the web search tool call. Always `web_search_call`. + - `Text object { type }` - - `"web_search_call"` + Unconstrained free-form text. - - `ComputerCall object { id, call_id, pending_safety_checks, 4 more }` + - `type: "text"` - A tool call to a computer use tool. See the - [computer use guide](/docs/guides/tools-computer-use) for more information. + Unconstrained text format. Always `text`. - - `id: string` + - `"text"` - The unique ID of the computer call. + - `Grammar object { definition, syntax, type }` - - `call_id: string` + A grammar defined by the user. - An identifier used when responding to the tool call with output. + - `definition: string` - - `pending_safety_checks: array of object { id, code, message }` + The grammar definition. - The pending safety checks for the computer call. + - `syntax: "lark" or "regex"` - - `id: string` + The syntax of the grammar definition. One of `lark` or `regex`. - The ID of the pending safety check. + - `"lark"` - - `code: optional string` + - `"regex"` - The type of the pending safety check. + - `type: "grammar"` - - `message: optional string` + Grammar format. Always `grammar`. - Details about the pending safety check. + - `"grammar"` - - `status: "in_progress" or "completed" or "incomplete"` + - `Namespace object { description, name, tools, type }` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + Groups function/custom tools under a shared namespace. - - `"in_progress"` + - `description: string` - - `"completed"` + A description of the namespace shown to the model. - - `"incomplete"` + - `name: string` - - `type: "computer_call"` + The namespace name used in tool calls (for example, `crm`). - The type of the computer call. Always `computer_call`. + - `tools: array of object { name, type, allowed_callers, 5 more } or object { name, type, allowed_callers, 3 more }` - - `"computer_call"` + The function/custom tools available inside this namespace. - - `action: optional ComputerAction` + - `Function object { name, type, allowed_callers, 5 more }` - A click action. + - `name: string` - - `actions: optional ComputerActionList` + - `type: "function"` - Flattened batched actions for `computer_use`. Each action includes an - `type` discriminator and action-specific fields. + - `"function"` - - `ComputerCallOutput object { id, call_id, output, 4 more }` + - `allowed_callers: optional array of "direct" or "programmatic"` - - `id: string` + The tool invocation context(s). - The unique ID of the computer call tool output. + - `"direct"` - - `call_id: string` + - `"programmatic"` - The ID of the computer tool call that produced the output. + - `defer_loading: optional boolean` - - `output: ResponseComputerToolCallOutputScreenshot` + Whether this function should be deferred and discovered via tool search. - A computer screenshot image used with the computer use tool. + - `description: optional string` - - `status: "completed" or "incomplete" or "failed" or "in_progress"` + - `output_schema: optional map[unknown]` - The status of the message input. One of `in_progress`, `completed`, or - `incomplete`. Populated when input items are returned via API. + A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. - - `"completed"` + - `parameters: optional unknown` - - `"incomplete"` + - `strict: optional boolean` - - `"failed"` + Whether to enforce strict parameter validation. If omitted, Responses attempts to use strict validation when the schema is compatible, and falls back to non-strict validation otherwise. - - `"in_progress"` + - `Custom object { name, type, allowed_callers, 3 more }` - - `type: "computer_call_output"` + 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 computer tool call output. Always `computer_call_output`. + - `name: string` - - `"computer_call_output"` + The name of the custom tool, used to identify it in tool calls. - - `acknowledged_safety_checks: optional array of object { id, code, message }` + - `type: "custom"` - The safety checks reported by the API that have been acknowledged by the - developer. + The type of the custom tool. Always `custom`. - - `id: string` + - `"custom"` - The ID of the pending safety check. + - `allowed_callers: optional array of "direct" or "programmatic"` - - `code: optional string` + The tool invocation context(s). - The type of the pending safety check. + - `"direct"` - - `message: optional string` + - `"programmatic"` - Details about the pending safety check. + - `defer_loading: optional boolean` - - `created_by: optional string` + Whether this tool should be deferred and discovered via tool search. - The identifier of the actor that created the item. + - `description: optional string` - - `Reasoning object { id, summary, type, 3 more }` + Optional description of the custom tool, used to provide more context. - 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). + - `format: optional CustomToolInputFormat` - - `id: string` + The input format for the custom tool. Default is unconstrained text. - The unique identifier of the reasoning content. + - `type: "namespace"` - - `summary: array of SummaryTextContent` + The type of the tool. Always `namespace`. - Reasoning summary content. + - `"namespace"` - - `text: string` + - `ToolSearch object { type, description, execution, parameters }` - A summary of the reasoning output from the model so far. + Hosted or BYOT tool search configuration for deferred tools. - - `type: "summary_text"` + - `type: "tool_search"` - The type of the object. Always `summary_text`. + The type of the tool. Always `tool_search`. - - `type: "reasoning"` + - `"tool_search"` - The type of the object. Always `reasoning`. + - `description: optional string` - - `"reasoning"` + Description shown to the model for a client-executed tool search tool. - - `content: optional array of object { text, type }` + - `execution: optional "server" or "client"` - Reasoning text content. + Whether tool search is executed by the server or by the client. - - `text: string` + - `"server"` - The reasoning text from the model. + - `"client"` - - `type: "reasoning_text"` + - `parameters: optional unknown` - The type of the reasoning text. Always `reasoning_text`. + Parameter schema for a client-executed tool search tool. - - `"reasoning_text"` + - `WebSearchPreview object { type, search_content_types, search_context_size, user_location }` - - `encrypted_content: optional 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 encrypted content of the reasoning item. This is populated by default - for reasoning items returned by `POST /v1/responses` and WebSocket - `response.create` requests. + - `type: "web_search_preview" or "web_search_preview_2025_03_11"` - - `status: optional "in_progress" or "completed" or "incomplete"` + The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `"web_search_preview"` - - `"in_progress"` + - `"web_search_preview_2025_03_11"` - - `"completed"` + - `search_content_types: optional array of "text" or "image"` - - `"incomplete"` + - `"text"` - - `Program object { id, call_id, code, 2 more }` + - `"image"` - - `id: string` + - `search_context_size: optional "low" or "medium" or "high"` - The unique ID of the program 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. - - `call_id: string` + - `"low"` - The stable call ID of the program item. + - `"medium"` - - `code: string` + - `"high"` - The JavaScript source executed by programmatic tool calling. + - `user_location: optional object { type, city, country, 2 more }` - - `fingerprint: string` + The user's location. - Opaque program replay fingerprint that must be round-tripped. + - `type: "approximate"` - - `type: "program"` + The type of location approximation. Always `approximate`. - The type of the item. Always `program`. + - `"approximate"` - - `"program"` + - `city: optional string` - - `ProgramOutput object { id, call_id, result, 2 more }` + Free text input for the city of the user, e.g. `San Francisco`. - - `id: string` + - `country: optional string` - The unique ID of the program output item. + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - - `call_id: string` + - `region: optional string` - The call ID of the program item. + Free text input for the region of the user, e.g. `California`. - - `result: string` + - `timezone: optional string` - The result produced by the program item. + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - - `status: "completed" or "incomplete"` + - `ApplyPatch object { type, allowed_callers }` - The terminal status of the program output item. + Allows the assistant to create, delete, or update files using unified diffs. - - `"completed"` + - `type: "apply_patch"` - - `"incomplete"` + The type of the tool. Always `apply_patch`. - - `type: "program_output"` + - `"apply_patch"` - The type of the item. Always `program_output`. + - `allowed_callers: optional array of "direct" or "programmatic"` - - `"program_output"` + The tool invocation context(s). - - `ToolSearchCall object { id, arguments, call_id, 4 more }` + - `"direct"` - - `id: string` + - `"programmatic"` - The unique ID of the tool search call item. + - `type: "tool_search_output"` - - `arguments: unknown` + The item type. Always `tool_search_output`. - Arguments used for the tool search call. + - `"tool_search_output"` - - `call_id: string` + - `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: "server" or "client"` + - `execution: optional "server" or "client"` Whether tool search was executed by the server or by the client. @@ -20666,9 +20060,9 @@ Retrieves a model response with the given ID. - `"client"` - - `status: "in_progress" or "completed" or "incomplete"` + - `status: optional "in_progress" or "completed" or "incomplete"` - The status of the tool search call item that was recorded. + The status of the tool search output. - `"in_progress"` @@ -20676,47 +20070,17 @@ Retrieves a model response with the given ID. - `"incomplete"` - - `type: "tool_search_call"` - - The type of the item. Always `tool_search_call`. - - - `"tool_search_call"` - - - `created_by: optional string` - - The identifier of the actor that created the item. - - - `ToolSearchOutput object { id, call_id, execution, 4 more }` - - - `id: string` - - The unique ID of the tool search output item. - - - `call_id: string` - - 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 tool search output item that was recorded. + - `AdditionalTools object { role, tools, type, id }` - - `"in_progress"` + - `role: "developer"` - - `"completed"` + The role that provided the additional tools. Only `developer` is supported. - - `"incomplete"` + - `"developer"` - `tools: array of object { name, parameters, strict, 5 more } or object { type, vector_store_ids, filters, 2 more } or object { type } or 13 more` - The loaded tool definitions returned by tool search. + A list of additional tools made available at this item. - `Function object { name, parameters, strict, 5 more }` @@ -21527,1705 +20891,1540 @@ Retrieves a model response with the given ID. - `"programmatic"` - - `type: "tool_search_output"` + - `type: "additional_tools"` - The type of the item. Always `tool_search_output`. + The item type. Always `additional_tools`. - - `"tool_search_output"` + - `"additional_tools"` - - `created_by: optional string` + - `id: optional string` - The identifier of the actor that created the item. + The unique ID of this additional tools item. - - `AdditionalTools object { id, role, tools, type }` + - `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 ID of the additional tools item. + The unique identifier of the reasoning content. - - `role: "unknown" or "user" or "assistant" or 5 more` + - `summary: array of SummaryTextContent` - The role that provided the additional tools. + Reasoning summary content. - - `"unknown"` + - `text: string` - - `"user"` + A summary of the reasoning output from the model so far. - - `"assistant"` + - `type: "summary_text"` - - `"system"` + The type of the object. Always `summary_text`. - - `"critic"` + - `"summary_text"` - - `"discriminator"` + - `type: "reasoning"` - - `"developer"` + The type of the object. Always `reasoning`. - - `"tool"` + - `"reasoning"` - - `tools: array of object { name, parameters, strict, 5 more } or object { type, vector_store_ids, filters, 2 more } or object { type } or 13 more` + - `content: optional array of object { text, type }` - The additional tool definitions made available at this item. + Reasoning text content. - - `Function object { name, parameters, strict, 5 more }` + - `text: 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 reasoning text from the model. - - `name: string` + - `type: "reasoning_text"` - The name of the function to call. + The type of the reasoning text. Always `reasoning_text`. - - `parameters: map[unknown]` + - `"reasoning_text"` - A JSON schema object describing the parameters of the function. + - `encrypted_content: optional string` - - `strict: boolean` + The encrypted content of the reasoning item. This is populated by default + for reasoning items returned by `POST /v1/responses` and WebSocket + `response.create` requests. - Whether strict parameter validation is enforced for this function tool. + - `status: optional "in_progress" or "completed" or "incomplete"` - - `type: "function"` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - The type of the function tool. Always `function`. + - `"in_progress"` - - `"function"` + - `"completed"` - - `allowed_callers: optional array of "direct" or "programmatic"` + - `"incomplete"` - The tool invocation context(s). + - `Compaction object { encrypted_content, type, id }` - - `"direct"` + A compaction item generated by the [`v1/responses/compact` API](/docs/api-reference/responses/compact). - - `"programmatic"` + - `encrypted_content: string` - - `defer_loading: optional boolean` + The encrypted content of the compaction summary. - Whether this function is deferred and loaded via tool search. + - `type: "compaction"` - - `description: optional string` + The type of the item. Always `compaction`. - A description of the function. Used by the model to determine whether or not to call the function. + - `"compaction"` - - `output_schema: optional map[unknown]` + - `id: optional string` - A JSON schema object describing the JSON value encoded in string outputs for this function. + The ID of the compaction item. - - `FileSearch object { type, vector_store_ids, filters, 2 more }` + - `ImageGenerationCall object { id, result, status, type }` - A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). + An image generation request made by the model. - - `type: "file_search"` + - `id: string` - The type of the file search tool. Always `file_search`. + The unique ID of the image generation call. - - `"file_search"` + - `result: string` - - `vector_store_ids: array of string` + The generated image encoded in base64. - The IDs of the vector stores to search. + - `status: "in_progress" or "completed" or "generating" or "failed"` - - `filters: optional ComparisonFilter or CompoundFilter` + The status of the image generation call. - 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. + - `"generating"` - - `CompoundFilter object { filters, type }` + - `"failed"` - Combine multiple filters using `and` or `or`. + - `type: "image_generation_call"` - - `max_num_results: optional number` + The type of the image generation call. Always `image_generation_call`. - The maximum number of results to return. This number should be between 1 and 50 inclusive. + - `"image_generation_call"` - - `ranking_options: optional object { hybrid_search, ranker, score_threshold }` + - `CodeInterpreterCall object { id, code, container_id, 3 more }` - Ranking options for search. + A tool call to run code. - - `hybrid_search: optional object { embedding_weight, text_weight }` + - `id: string` - Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. + The unique ID of the code interpreter tool call. - - `embedding_weight: number` + - `code: string` - The weight of the embedding in the reciprocal ranking fusion. + The code to run, or null if not available. - - `text_weight: number` + - `container_id: string` - The weight of the text in the reciprocal ranking fusion. + The ID of the container used to run the code. - - `ranker: optional "auto" or "default-2024-11-15"` + - `outputs: array of object { logs, type } or object { type, url }` - The ranker to use for the file search. + 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 }` - - `"default-2024-11-15"` + The logs output from the code interpreter. - - `score_threshold: optional number` + - `logs: 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 logs output from the code interpreter. - - `Computer object { type }` + - `type: "logs"` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + The type of the output. Always `logs`. - - `type: "computer"` + - `"logs"` - The type of the computer tool. Always `computer`. + - `Image object { type, url }` - - `"computer"` + The image output from the code interpreter. - - `ComputerUsePreview object { display_height, display_width, environment, type }` + - `type: "image"` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + The type of the output. Always `image`. - - `display_height: number` + - `"image"` - The height of the computer display. + - `url: string` - - `display_width: number` + The URL of the image output from the code interpreter. - The width of the computer display. + - `status: "in_progress" or "completed" or "incomplete" or 2 more` - - `environment: "windows" or "mac" or "linux" or 2 more` + The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. - The type of computer environment to control. + - `"in_progress"` - - `"windows"` + - `"completed"` - - `"mac"` + - `"incomplete"` - - `"linux"` + - `"interpreting"` - - `"ubuntu"` + - `"failed"` - - `"browser"` + - `type: "code_interpreter_call"` - - `type: "computer_use_preview"` + The type of the code interpreter tool call. Always `code_interpreter_call`. - The type of the computer use tool. Always `computer_use_preview`. + - `"code_interpreter_call"` - - `"computer_use_preview"` + - `LocalShellCall object { id, action, call_id, 2 more }` - - `WebSearch object { type, filters, search_context_size, user_location }` + A tool call to run a command on the local shell. - Search the Internet for sources related to the prompt. Learn more about the - [web search tool](/docs/guides/tools-web-search). + - `id: string` - - `type: "web_search" or "web_search_2025_08_26"` + The unique ID of the local shell call. - The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. + - `action: object { command, env, type, 3 more }` - - `"web_search"` + Execute a shell command on the server. - - `"web_search_2025_08_26"` + - `command: array of string` - - `filters: optional object { allowed_domains }` + The command to run. - Filters for the search. + - `env: map[string]` - - `allowed_domains: optional array of string` + Environment variables to set for the command. - Allowed domains for the search. If not provided, all domains are allowed. - Subdomains of the provided domains are allowed as well. + - `type: "exec"` - Example: `["pubmed.ncbi.nlm.nih.gov"]` + The type of the local shell action. Always `exec`. - - `search_context_size: optional "low" or "medium" or "high"` + - `"exec"` - 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. + - `timeout_ms: optional number` - - `"low"` + Optional timeout in milliseconds for the command. - - `"medium"` + - `user: optional string` - - `"high"` + Optional user to run the command as. - - `user_location: optional object { city, country, region, 2 more }` + - `working_directory: optional string` - The approximate location of the user. + Optional working directory to run the command in. - - `city: optional string` + - `call_id: string` - Free text input for the city of the user, e.g. `San Francisco`. + The unique ID of the local shell tool call generated by the model. - - `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 local shell call. - - `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: "local_shell_call"` - - `type: optional "approximate"` + The type of the local shell call. Always `local_shell_call`. - The type of location approximation. Always `approximate`. + - `"local_shell_call"` - - `"approximate"` + - `LocalShellCallOutput object { id, output, type, status }` - - `Mcp object { server_label, type, allowed_callers, 9 more }` + The output of a local shell 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). + - `id: string` - - `server_label: string` + The unique ID of the local shell tool call generated by the model. - A label for this MCP server, used to identify it in tool calls. + - `output: string` - - `type: "mcp"` + A JSON string of the output of the local shell tool call. - The type of the MCP tool. Always `mcp`. + - `type: "local_shell_call_output"` - - `"mcp"` + The type of the local shell tool call output. Always `local_shell_call_output`. - - `allowed_callers: optional array of "direct" or "programmatic"` + - `"local_shell_call_output"` - The tool invocation context(s). + - `status: optional "in_progress" or "completed" or "incomplete"` - - `"direct"` + The status of the item. One of `in_progress`, `completed`, or `incomplete`. - - `"programmatic"` + - `"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` + - `ShellCall object { action, call_id, type, 4 more }` - A string array of allowed tool names + A tool representing a request to execute one or more shell commands. - - `McpToolFilter object { read_only, tool_names }` + - `action: object { commands, max_output_length, timeout_ms }` - A filter object to specify which tools are allowed. + The shell commands and limits that describe how to run the tool call. - - `read_only: optional boolean` + - `commands: array of 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. + Ordered shell commands for the execution environment to run. - - `tool_names: optional array of string` + - `max_output_length: optional number` - List of allowed tool names. + Maximum number of UTF-8 characters to capture from combined stdout and stderr output. - - `authorization: optional string` + - `timeout_ms: optional number` - 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. + Maximum wall-clock time in milliseconds to allow the shell commands to run. - - `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`, `connector_id`, or `tunnel_id` must be provided. Learn more - about service connectors [here](/docs/guides/tools-remote-mcp#connectors). + The unique ID of the shell tool call generated by the model. - Currently supported `connector_id` values are: + - `type: "shell_call"` - - 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 item. Always `shell_call`. - - `"connector_dropbox"` + - `"shell_call"` - - `"connector_gmail"` + - `id: optional string` - - `"connector_googlecalendar"` + The unique ID of the shell tool call. Populated when this item is returned via API. - - `"connector_googledrive"` + - `caller: optional object { type } or object { caller_id, type }` - - `"connector_microsoftteams"` + The execution context that produced this tool call. - - `"connector_outlookcalendar"` + - `Direct object { type }` - - `"connector_outlookemail"` + - `type: "direct"` - - `"connector_sharepoint"` + The caller type. Always `direct`. - - `defer_loading: optional boolean` + - `"direct"` - Whether this MCP tool is deferred and discovered via tool search. + - `Program object { caller_id, type }` - - `headers: optional map[string]` + - `caller_id: string` - Optional HTTP headers to send to the MCP server. Use for authentication - or other purposes. + The call ID of the program item that produced this tool call. - - `require_approval: optional object { always, never } or "always" or "never"` + - `type: "program"` - Specify which of the MCP server's tools require approval. + The caller type. Always `program`. - - `McpToolApprovalFilter object { always, never }` + - `"program"` - Specify which of the MCP server's tools require approval. Can be - `always`, `never`, or a filter object associated with tools - that require approval. + - `environment: optional LocalEnvironment or ContainerReference` - - `always: 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"` - - `never: optional object { read_only, tool_names }` + - `"completed"` - A filter object to specify which tools are allowed. + - `"incomplete"` - - `read_only: optional boolean` + - `ShellCallOutput object { call_id, output, type, 4 more }` - Indicates whether or not a tool modifies data or is read-only. If an - MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), - it will match this filter. + The streamed output items emitted by a shell tool call. - - `tool_names: optional array of string` + - `call_id: string` - List of allowed tool names. + The unique ID of the shell tool call generated by the model. - - `McpToolApprovalSetting = "always" or "never"` + - `output: array of ResponseFunctionShellCallOutputContent` - 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. + Captured chunks of stdout and stderr output, along with their associated outcomes. - - `"always"` + - `outcome: object { type } or object { exit_code, type }` - - `"never"` + The exit or timeout outcome associated with this shell call. - - `server_description: optional string` + - `Timeout object { type }` - Optional description of the MCP server, used to provide more context. + Indicates that the shell call exceeded its configured time limit. - - `server_url: optional string` + - `type: "timeout"` - The URL for the MCP server. One of `server_url`, `connector_id`, or - `tunnel_id` must be provided. + The outcome type. Always `timeout`. - - `tunnel_id: optional string` + - `"timeout"` - The Secure MCP Tunnel ID to use instead of a direct server URL. One of - `server_url`, `connector_id`, or `tunnel_id` must be provided. + - `Exit object { exit_code, type }` - - `CodeInterpreter object { container, type, allowed_callers }` + Indicates that the shell commands finished and returned an exit code. - A tool that runs Python code to help generate a response to a prompt. + - `exit_code: number` - - `container: string or object { type, file_ids, memory_limit, network_policy }` + The exit code returned by the shell process. - The code interpreter container. Can be a container ID or an object that - specifies uploaded file IDs to make available to your code, along with an - optional `memory_limit` setting. + - `type: "exit"` - - `string` + The outcome type. Always `exit`. - The container ID. + - `"exit"` - - `CodeInterpreterToolAuto object { type, file_ids, memory_limit, network_policy }` + - `stderr: string` - Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. + Captured stderr output for the shell call. - - `type: "auto"` + - `stdout: string` - Always `auto`. + Captured stdout output for the shell call. - - `"auto"` + - `type: "shell_call_output"` - - `file_ids: optional array of string` + The type of the item. Always `shell_call_output`. - An optional list of uploaded files to make available to your code. + - `"shell_call_output"` - - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` + - `id: optional string` - The memory limit for the code interpreter container. + The unique ID of the shell tool call output. Populated when this item is returned via API. - - `"1g"` + - `caller: optional object { type } or object { caller_id, type }` - - `"4g"` + The execution context that produced this tool call. - - `"16g"` + - `Direct object { type }` - - `"64g"` + - `type: "direct"` - - `network_policy: optional ContainerNetworkPolicyDisabled or ContainerNetworkPolicyAllowlist` + The caller type. Always `direct`. - Network access policy for the container. + - `"direct"` - - `ContainerNetworkPolicyDisabled object { type }` + - `Program object { caller_id, type }` - - `ContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` + - `caller_id: string` - - `type: "code_interpreter"` + The call ID of the program item that produced this tool call. - The type of the code interpreter tool. Always `code_interpreter`. + - `type: "program"` - - `"code_interpreter"` + The caller type. Always `program`. - - `allowed_callers: optional array of "direct" or "programmatic"` + - `"program"` - The tool invocation context(s). + - `max_output_length: optional number` - - `"direct"` + The maximum number of UTF-8 characters captured for this shell call's combined output. - - `"programmatic"` + - `status: optional "in_progress" or "completed" or "incomplete"` - - `ProgrammaticToolCalling object { type }` + The status of the shell call output. - - `type: "programmatic_tool_calling"` + - `"in_progress"` - The type of the tool. Always `programmatic_tool_calling`. + - `"completed"` - - `"programmatic_tool_calling"` + - `"incomplete"` - - `ImageGeneration object { type, action, background, 9 more }` + - `ApplyPatchCall object { call_id, operation, status, 3 more }` - A tool that generates images using the GPT image models. + A tool call representing a request to create, delete, or update files using diff patches. - - `type: "image_generation"` + - `call_id: string` - The type of the image generation tool. Always `image_generation`. + The unique ID of the apply patch tool call generated by the model. - - `"image_generation"` + - `operation: object { diff, path, type } or object { path, type } or object { diff, path, type }` - - `action: optional "generate" or "edit" or "auto"` + The specific create, delete, or update instruction for the apply_patch tool call. - Whether to generate a new image or edit an existing image. Default: `auto`. + - `CreateFile object { diff, path, type }` - - `"generate"` + Instruction for creating a new file via the apply_patch tool. - - `"edit"` + - `diff: string` - - `"auto"` + Unified diff content to apply when creating the file. - - `background: optional "transparent" or "opaque" or "auto"` + - `path: string` - Background type for the generated image. One of `transparent`, - `opaque`, or `auto`. Default: `auto`. + Path of the file to create relative to the workspace root. - - `"transparent"` + - `type: "create_file"` - - `"opaque"` + The operation type. Always `create_file`. - - `"auto"` + - `"create_file"` - - `input_fidelity: optional "high" or "low"` + - `DeleteFile object { path, type }` - 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`. + Instruction for deleting an existing file via the apply_patch tool. - - `"high"` + - `path: string` - - `"low"` + Path of the file to delete relative to the workspace root. - - `input_image_mask: optional object { file_id, image_url }` + - `type: "delete_file"` - Optional mask for inpainting. Contains `image_url` - (string, optional) and `file_id` (string, optional). + The operation type. Always `delete_file`. - - `file_id: optional string` + - `"delete_file"` - File ID for the mask image. + - `UpdateFile object { diff, path, type }` - - `image_url: optional string` + Instruction for updating an existing file via the apply_patch tool. - Base64-encoded mask image. + - `diff: string` - - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` + Unified diff content to apply to the existing file. - The image generation model to use. Default: `gpt-image-1`. + - `path: string` - - `string` + Path of the file to update relative to the workspace root. - - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` + - `type: "update_file"` - The image generation model to use. Default: `gpt-image-1`. + The operation type. Always `update_file`. - - `"gpt-image-1"` + - `"update_file"` - - `"gpt-image-1-mini"` + - `status: "in_progress" or "completed"` - - `"gpt-image-1.5"` + The status of the apply patch tool call. One of `in_progress` or `completed`. - - `moderation: optional "auto" or "low"` + - `"in_progress"` - Moderation level for the generated image. Default: `auto`. + - `"completed"` - - `"auto"` + - `type: "apply_patch_call"` - - `"low"` + The type of the item. Always `apply_patch_call`. - - `output_compression: optional number` + - `"apply_patch_call"` - Compression level for the output image. Default: 100. + - `id: optional string` - - `output_format: optional "png" or "webp" or "jpeg"` + The unique ID of the apply patch tool call. Populated when this item is returned via API. - The output format of the generated image. One of `png`, `webp`, or - `jpeg`. Default: `png`. + - `caller: optional object { type } or object { caller_id, type }` - - `"png"` + The execution context that produced this tool call. - - `"webp"` + - `Direct object { type }` - - `"jpeg"` + - `type: "direct"` - - `partial_images: optional number` + The caller type. Always `direct`. - Number of partial images to generate in streaming mode, from 0 (default value) to 3. + - `"direct"` - - `quality: optional "low" or "medium" or "high" or "auto"` + - `Program object { caller_id, type }` - The quality of the generated image. One of `low`, `medium`, `high`, - or `auto`. Default: `auto`. + - `caller_id: string` - - `"low"` + The call ID of the program item that produced this tool call. - - `"medium"` + - `type: "program"` - - `"high"` + The caller type. Always `program`. - - `"auto"` + - `"program"` - - `size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or "auto"` + - `ApplyPatchCallOutput object { call_id, status, type, 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`. + The streamed output emitted by an apply patch tool call. - - `string` + - `call_id: string` - - `"1024x1024" or "1024x1536" or "1536x1024" or "auto"` + The unique ID of the apply patch tool call generated by the model. - 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`. + - `status: "completed" or "failed"` - - `"1024x1024"` + The status of the apply patch tool call output. One of `completed` or `failed`. - - `"1024x1536"` + - `"completed"` - - `"1536x1024"` + - `"failed"` - - `"auto"` + - `type: "apply_patch_call_output"` - - `LocalShell object { type }` + The type of the item. Always `apply_patch_call_output`. - A tool that allows the model to execute shell commands in a local environment. + - `"apply_patch_call_output"` - - `type: "local_shell"` + - `id: optional string` - The type of the local shell tool. Always `local_shell`. + The unique ID of the apply patch tool call output. Populated when this item is returned via API. - - `"local_shell"` + - `caller: optional object { type } or object { caller_id, type }` - - `Shell object { type, allowed_callers, environment }` + The execution context that produced this tool call. - A tool that allows the model to execute shell commands. + - `Direct object { type }` - - `type: "shell"` + - `type: "direct"` - The type of the shell tool. Always `shell`. + The caller type. Always `direct`. - - `"shell"` + - `"direct"` - - `allowed_callers: optional array of "direct" or "programmatic"` + - `Program object { caller_id, type }` - The tool invocation context(s). + - `caller_id: string` - - `"direct"` + The call ID of the program item that produced this tool call. - - `"programmatic"` + - `type: "program"` - - `environment: optional ContainerAuto or LocalEnvironment or ContainerReference` + The caller type. Always `program`. - - `ContainerAuto object { type, file_ids, memory_limit, 2 more }` + - `"program"` - - `LocalEnvironment object { type, skills }` + - `output: optional string` - - `ContainerReference object { container_id, type }` + Optional human-readable log text from the apply patch tool (e.g., patch results or errors). - - `Custom object { name, type, allowed_callers, 3 more }` + - `McpListTools object { id, server_label, tools, 2 more }` - A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) + A list of tools available on an MCP server. - - `name: string` + - `id: string` - The name of the custom tool, used to identify it in tool calls. + The unique ID of the list. - - `type: "custom"` + - `server_label: string` - The type of the custom tool. Always `custom`. + The label of the MCP server. - - `"custom"` + - `tools: array of object { input_schema, name, annotations, description }` - - `allowed_callers: optional array of "direct" or "programmatic"` + The tools available on the server. - The tool invocation context(s). + - `input_schema: unknown` - - `"direct"` + The JSON schema describing the tool's input. - - `"programmatic"` + - `name: string` - - `defer_loading: optional boolean` + The name of the tool. - Whether this tool should be deferred and discovered via tool search. + - `annotations: optional unknown` + + Additional annotations about the tool. - `description: optional string` - Optional description of the custom tool, used to provide more context. + The description of the tool. - - `format: optional CustomToolInputFormat` + - `type: "mcp_list_tools"` - The input format for the custom tool. Default is unconstrained text. + The type of the item. Always `mcp_list_tools`. - - `Namespace object { description, name, tools, type }` + - `"mcp_list_tools"` - Groups function/custom tools under a shared namespace. + - `error: optional string` - - `description: string` + Error message if the server could not list tools. - A description of the namespace shown to the model. + - `McpApprovalRequest object { id, arguments, name, 2 more }` - - `name: string` + A request for human approval of a tool invocation. - The namespace name used in tool calls (for example, `crm`). + - `id: string` - - `tools: array of object { name, type, allowed_callers, 5 more } or object { name, type, allowed_callers, 3 more }` + The unique ID of the approval request. - The function/custom tools available inside this namespace. + - `arguments: string` - - `Function object { name, type, allowed_callers, 5 more }` + A JSON string of arguments for the tool. - `name: string` - - `type: "function"` + The name of the tool to run. - - `"function"` + - `server_label: string` - - `allowed_callers: optional array of "direct" or "programmatic"` + The label of the MCP server making the request. - The tool invocation context(s). + - `type: "mcp_approval_request"` - - `"direct"` + The type of the item. Always `mcp_approval_request`. - - `"programmatic"` + - `"mcp_approval_request"` - - `defer_loading: optional boolean` + - `McpApprovalResponse object { approval_request_id, approve, type, 2 more }` - Whether this function should be deferred and discovered via tool search. + A response to an MCP approval request. - - `description: optional string` + - `approval_request_id: string` - - `output_schema: optional map[unknown]` + The ID of the approval request being answered. - A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. + - `approve: boolean` - - `parameters: optional unknown` + Whether the request was approved. - - `strict: optional boolean` + - `type: "mcp_approval_response"` - Whether to enforce strict parameter validation. If omitted, Responses attempts to use strict validation when the schema is compatible, and falls back to non-strict validation otherwise. + The type of the item. Always `mcp_approval_response`. - - `Custom object { name, type, allowed_callers, 3 more }` + - `"mcp_approval_response"` - A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) + - `id: optional string` - - `name: string` + The unique ID of the approval response - The name of the custom tool, used to identify it in tool calls. + - `reason: optional string` - - `type: "custom"` + Optional reason for the decision. - The type of the custom tool. Always `custom`. + - `McpCall object { id, arguments, name, 6 more }` - - `"custom"` + An invocation of a tool on an MCP server. - - `allowed_callers: optional array of "direct" or "programmatic"` + - `id: string` - The tool invocation context(s). + The unique ID of the tool call. - - `"direct"` + - `arguments: string` - - `"programmatic"` + 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, 2 more }` - 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, prompt_cache_breakpoint }` - - `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, 2 more }` - - `"low"` + An image input to the model. Learn about [image inputs](/docs/guides/vision). - - `"medium"` + - `ResponseInputFile object { type, detail, file_data, 4 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` + - `caller: optional object { type } or object { caller_id, type }` - Free text input for the city of the user, e.g. `San Francisco`. + The execution context that produced this tool call. - - `country: optional string` + - `Direct object { type }` - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + - `type: "direct"` - - `region: optional string` + The caller type. Always `direct`. - Free text input for the region of the user, e.g. `California`. + - `"direct"` - - `timezone: optional string` + - `Program object { caller_id, type }` - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + - `caller_id: string` - - `ApplyPatch object { type, allowed_callers }` + The call ID of the program item that produced this tool call. - Allows the assistant to create, delete, or update files using unified diffs. + - `type: "program"` - - `type: "apply_patch"` + The caller type. Always `program`. - The type of the tool. Always `apply_patch`. + - `"program"` - - `"apply_patch"` + - `CustomToolCall object { call_id, input, name, 4 more }` - - `allowed_callers: optional array of "direct" or "programmatic"` - - The tool invocation context(s). - - - `"direct"` - - - `"programmatic"` - - - `type: "additional_tools"` + A call to a custom tool created by the model. - The type of the item. Always `additional_tools`. + - `call_id: string` - - `"additional_tools"` + An identifier used to map this custom tool call to a tool call output. - - `Compaction object { id, encrypted_content, type, created_by }` + - `input: string` - A compaction item generated by the [`v1/responses/compact` API](/docs/api-reference/responses/compact). + The input for the custom tool call generated by the model. - - `id: string` + - `name: string` - The unique ID of the compaction item. + The name of the custom tool being called. - - `encrypted_content: string` + - `type: "custom_tool_call"` - The encrypted content that was produced by compaction. + The type of the custom tool call. Always `custom_tool_call`. - - `type: "compaction"` + - `"custom_tool_call"` - The type of the item. Always `compaction`. + - `id: optional string` - - `"compaction"` + The unique ID of the custom tool call in the OpenAI platform. - - `created_by: optional string` + - `caller: optional object { type } or object { caller_id, type }` - The identifier of the actor that created the item. + The execution context that produced this tool call. - - `ImageGenerationCall object { id, result, status, type }` + - `Direct object { type }` - An image generation request made by the model. + - `type: "direct"` - - `id: string` + - `"direct"` - The unique ID of the image generation call. + - `Program object { caller_id, type }` - - `result: string` + - `caller_id: string` - The generated image encoded in base64. + The call ID of the program item that produced this tool call. - - `status: "in_progress" or "completed" or "generating" or "failed"` + - `type: "program"` - The status of the image generation call. + - `"program"` - - `"in_progress"` + - `namespace: optional string` - - `"completed"` + The namespace of the custom tool being called. - - `"generating"` + - `CompactionTrigger object { type }` - - `"failed"` + Compacts the current context. Must be the final input item. - - `type: "image_generation_call"` + - `type: "compaction_trigger"` - The type of the image generation call. Always `image_generation_call`. + The type of the item. Always `compaction_trigger`. - - `"image_generation_call"` + - `"compaction_trigger"` - - `CodeInterpreterCall object { id, code, container_id, 3 more }` + - `ItemReference object { id, type }` - A tool call to run code. + An internal identifier for an item to reference. - `id: string` - The unique ID of the code interpreter tool call. + The ID of the item to reference. - - `code: string` + - `type: optional "item_reference"` - The code to run, or null if not available. + The type of item to reference. Always `item_reference`. - - `container_id: string` + - `"item_reference"` - The ID of the container used to run the code. + - `Program object { id, call_id, code, 2 more }` - - `outputs: array of object { logs, type } or object { type, url }` + - `id: string` - The outputs generated by the code interpreter, such as logs or images. - Can be null if no outputs are available. + The unique ID of this program item. - - `Logs object { logs, type }` + - `call_id: string` - The logs output from the code interpreter. + The stable call ID of the program item. - - `logs: string` + - `code: string` - The logs output from the code interpreter. + The JavaScript source executed by programmatic tool calling. - - `type: "logs"` + - `fingerprint: string` - The type of the output. Always `logs`. + Opaque program replay fingerprint that must be round-tripped. - - `"logs"` + - `type: "program"` - - `Image object { type, url }` + The item type. Always `program`. - The image output from the code interpreter. + - `"program"` - - `type: "image"` + - `ProgramOutput object { id, call_id, result, 2 more }` - The type of the output. Always `image`. + - `id: string` - - `"image"` + The unique ID of this program output item. - - `url: string` + - `call_id: string` - The URL of the image output from the code interpreter. + The call ID of the program item. - - `status: "in_progress" or "completed" or "incomplete" or 2 more` + - `result: string` - The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. + The result produced by the program item. - - `"in_progress"` + - `status: "completed" or "incomplete"` + + The terminal status of the program output. - `"completed"` - `"incomplete"` - - `"interpreting"` + - `type: "program_output"` - - `"failed"` + The item type. Always `program_output`. - - `type: "code_interpreter_call"` + - `"program_output"` - The type of the code interpreter tool call. Always `code_interpreter_call`. +- `instructions: optional string` - - `"code_interpreter_call"` + A system (or developer) message inserted into the model's context. - - `LocalShellCall object { id, action, call_id, 2 more }` + When using along with `previous_response_id`, the instructions from a previous + response will not be carried over to the next response. This makes it simple + to swap out system (or developer) messages in new responses. - A tool call to run a command on the local shell. +- `max_output_tokens: optional number` - - `id: string` + An upper bound for the number of tokens that can be generated for a response, including visible output tokens and [reasoning tokens](/docs/guides/reasoning). - The unique ID of the local shell call. +- `max_tool_calls: optional number` - - `action: object { command, env, type, 3 more }` + The maximum number of total calls to built-in tools that can be processed in a response. This maximum number applies across all built-in tool calls, not per individual tool. Any further attempts to call a tool by the model will be ignored. - Execute a shell command on the server. +- `metadata: optional Metadata` - - `command: array of 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 command to run. + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - - `env: map[string]` +- `model: optional ResponsesModel` - Environment variables to set for the command. + Model ID used to generate the response, like `gpt-4o` or `o3`. OpenAI + offers a wide range of models with different capabilities, performance + characteristics, and price points. Refer to the [model guide](/docs/models) + to browse and compare available models. - - `type: "exec"` + - `string` - The type of the local shell action. Always `exec`. + - `"gpt-5.6-sol" or "gpt-5.6-terra" or "gpt-5.6-luna" or 78 more` - - `"exec"` + - `"gpt-5.6-sol"` - - `timeout_ms: optional number` + - `"gpt-5.6-terra"` - Optional timeout in milliseconds for the command. + - `"gpt-5.6-luna"` - - `user: optional string` + - `"gpt-5.4"` - Optional user to run the command as. + - `"gpt-5.4-mini"` - - `working_directory: optional string` + - `"gpt-5.4-nano"` - Optional working directory to run the command in. + - `"gpt-5.4-mini-2026-03-17"` - - `call_id: string` + - `"gpt-5.4-nano-2026-03-17"` - The unique ID of the local shell tool call generated by the model. + - `"gpt-5.3-chat-latest"` - - `status: "in_progress" or "completed" or "incomplete"` + - `"gpt-5.2"` - The status of the local shell call. + - `"gpt-5.2-2025-12-11"` - - `"in_progress"` + - `"gpt-5.2-chat-latest"` - - `"completed"` + - `"gpt-5.2-pro"` - - `"incomplete"` + - `"gpt-5.2-pro-2025-12-11"` - - `type: "local_shell_call"` + - `"gpt-5.1"` - The type of the local shell call. Always `local_shell_call`. + - `"gpt-5.1-2025-11-13"` - - `"local_shell_call"` + - `"gpt-5.1-codex"` - - `LocalShellCallOutput object { id, output, type, status }` + - `"gpt-5.1-mini"` - The output of a local shell tool call. + - `"gpt-5.1-chat-latest"` - - `id: string` + - `"gpt-5"` - The unique ID of the local shell tool call generated by the model. + - `"gpt-5-mini"` - - `output: string` + - `"gpt-5-nano"` - A JSON string of the output of the local shell tool call. + - `"gpt-5-2025-08-07"` - - `type: "local_shell_call_output"` + - `"gpt-5-mini-2025-08-07"` - The type of the local shell tool call output. Always `local_shell_call_output`. + - `"gpt-5-nano-2025-08-07"` - - `"local_shell_call_output"` + - `"gpt-5-chat-latest"` - - `status: optional "in_progress" or "completed" or "incomplete"` + - `"gpt-4.1"` - The status of the item. One of `in_progress`, `completed`, or `incomplete`. + - `"gpt-4.1-mini"` - - `"in_progress"` + - `"gpt-4.1-nano"` - - `"completed"` + - `"gpt-4.1-2025-04-14"` - - `"incomplete"` + - `"gpt-4.1-mini-2025-04-14"` - - `ShellCall object { id, action, call_id, 5 more }` + - `"gpt-4.1-nano-2025-04-14"` - A tool call that executes one or more shell commands in a managed environment. + - `"o4-mini"` - - `id: string` + - `"o4-mini-2025-04-16"` - The unique ID of the shell tool call. Populated when this item is returned via API. + - `"o3"` - - `action: object { commands, max_output_length, timeout_ms }` + - `"o3-2025-04-16"` - The shell commands and limits that describe how to run the tool call. + - `"o3-mini"` - - `commands: array of string` + - `"o3-mini-2025-01-31"` - - `max_output_length: number` + - `"o1"` - Optional maximum number of characters to return from each command. + - `"o1-2024-12-17"` - - `timeout_ms: number` + - `"o1-preview"` - Optional timeout in milliseconds for the commands. + - `"o1-preview-2024-09-12"` - - `call_id: string` + - `"o1-mini"` - The unique ID of the shell tool call generated by the model. + - `"o1-mini-2024-09-12"` - - `environment: ResponseLocalEnvironment or ResponseContainerReference` + - `"gpt-4o"` - Represents the use of a local environment to perform shell actions. + - `"gpt-4o-2024-11-20"` - - `ResponseLocalEnvironment object { type }` + - `"gpt-4o-2024-08-06"` - Represents the use of a local environment to perform shell actions. + - `"gpt-4o-2024-05-13"` - - `type: "local"` + - `"gpt-4o-audio-preview"` - The environment type. Always `local`. + - `"gpt-4o-audio-preview-2024-10-01"` - - `"local"` + - `"gpt-4o-audio-preview-2024-12-17"` - - `ResponseContainerReference object { container_id, type }` + - `"gpt-4o-audio-preview-2025-06-03"` - Represents a container created with /v1/containers. + - `"gpt-4o-mini-audio-preview"` - - `container_id: string` + - `"gpt-4o-mini-audio-preview-2024-12-17"` - - `type: "container_reference"` + - `"gpt-4o-search-preview"` - The environment type. Always `container_reference`. + - `"gpt-4o-mini-search-preview"` - - `"container_reference"` + - `"gpt-4o-search-preview-2025-03-11"` - - `status: "in_progress" or "completed" or "incomplete"` + - `"gpt-4o-mini-search-preview-2025-03-11"` - The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. + - `"chatgpt-4o-latest"` - - `"in_progress"` + - `"codex-mini-latest"` - - `"completed"` + - `"gpt-4o-mini"` - - `"incomplete"` + - `"gpt-4o-mini-2024-07-18"` - - `type: "shell_call"` + - `"gpt-4-turbo"` - The type of the item. Always `shell_call`. + - `"gpt-4-turbo-2024-04-09"` - - `"shell_call"` + - `"gpt-4-0125-preview"` - - `caller: optional object { type } or object { caller_id, type }` + - `"gpt-4-turbo-preview"` - The execution context that produced this tool call. + - `"gpt-4-1106-preview"` - - `Direct object { type }` + - `"gpt-4-vision-preview"` - - `type: "direct"` + - `"gpt-4"` - - `"direct"` + - `"gpt-4-0314"` - - `Program object { caller_id, type }` + - `"gpt-4-0613"` - - `caller_id: string` + - `"gpt-4-32k"` - The call ID of the program item that produced this tool call. + - `"gpt-4-32k-0314"` - - `type: "program"` + - `"gpt-4-32k-0613"` - - `"program"` + - `"gpt-3.5-turbo"` - - `created_by: optional string` + - `"gpt-3.5-turbo-16k"` - The ID of the entity that created this tool call. + - `"gpt-3.5-turbo-0301"` - - `ShellCallOutput object { id, call_id, max_output_length, 5 more }` + - `"gpt-3.5-turbo-0613"` - The output of a shell tool call that was emitted. + - `"gpt-3.5-turbo-1106"` - - `id: string` + - `"gpt-3.5-turbo-0125"` - The unique ID of the shell call output. Populated when this item is returned via API. + - `"gpt-3.5-turbo-16k-0613"` - - `call_id: string` + - `ResponsesOnlyModel = "o1-pro" or "o1-pro-2025-03-19" or "o3-pro" or 11 more` - The unique ID of the shell tool call generated by the model. + - `"o1-pro"` - - `max_output_length: number` + - `"o1-pro-2025-03-19"` - The maximum length of the shell command output. This is generated by the model and should be passed back with the raw output. + - `"o3-pro"` - - `output: array of object { outcome, stderr, stdout, created_by }` + - `"o3-pro-2025-06-10"` - An array of shell call output contents + - `"o3-deep-research"` - - `outcome: object { type } or object { exit_code, type }` + - `"o3-deep-research-2025-06-26"` - Represents either an exit outcome (with an exit code) or a timeout outcome for a shell call output chunk. + - `"o4-mini-deep-research"` - - `Timeout object { type }` + - `"o4-mini-deep-research-2025-06-26"` - Indicates that the shell call exceeded its configured time limit. + - `"computer-use-preview"` - - `type: "timeout"` + - `"computer-use-preview-2025-03-11"` - The outcome type. Always `timeout`. + - `"gpt-5-codex"` - - `"timeout"` + - `"gpt-5-pro"` - - `Exit object { exit_code, type }` + - `"gpt-5-pro-2025-10-06"` - Indicates that the shell commands finished and returned an exit code. + - `"gpt-5.1-codex-max"` - - `exit_code: number` +- `moderation: optional object { model, policy }` - Exit code from the shell process. + Configuration for running moderation on the input and output of this response. - - `type: "exit"` + - `model: string` - The outcome type. Always `exit`. + The moderation model to use for moderated completions, e.g. 'omni-moderation-latest'. - - `"exit"` + - `policy: optional object { input, output }` - - `stderr: string` + The policy to apply to moderated response input and output. - The standard error output that was captured. + - `input: optional object { mode }` - - `stdout: string` + The moderation policy for the response input. - The standard output that was captured. + - `mode: "score" or "block"` - - `created_by: optional string` + - `"score"` - The identifier of the actor that created the item. + - `"block"` - - `status: "in_progress" or "completed" or "incomplete"` + - `output: optional object { mode }` - The status of the shell call output. One of `in_progress`, `completed`, or `incomplete`. + The moderation policy for the response output. - - `"in_progress"` + - `mode: "score" or "block"` - - `"completed"` + - `"score"` - - `"incomplete"` + - `"block"` - - `type: "shell_call_output"` +- `parallel_tool_calls: optional boolean` - The type of the shell call output. Always `shell_call_output`. + Whether to allow the model to run tool calls in parallel. - - `"shell_call_output"` +- `previous_response_id: optional string` - - `caller: optional object { type } or object { caller_id, type }` + The unique ID of the previous response to the model. Use this to + create multi-turn conversations. Learn more about + [conversation state](/docs/guides/conversation-state). Cannot be used in conjunction with `conversation`. - The execution context that produced this tool call. +- `prompt: optional ResponsePrompt` - - `Direct object { type }` + Reference to a prompt template and its variables. + [Learn more](/docs/guides/text?api-mode=responses#reusable-prompts). - - `type: "direct"` + - `id: string` - - `"direct"` + The unique identifier of the prompt template to use. - - `Program object { caller_id, type }` + - `variables: optional map[string or ResponseInputText or ResponseInputImage or ResponseInputFile]` - - `caller_id: string` + Optional map of values to substitute in for variables in your + prompt. The substitution values can either be strings, or other + Response input types like images or files. - The call ID of the program item that produced this tool call. + - `string` - - `type: "program"` + - `ResponseInputText object { text, type, prompt_cache_breakpoint }` - - `"program"` + A text input to the model. - - `created_by: optional string` + - `ResponseInputImage object { detail, type, file_id, 2 more }` - The identifier of the actor that created the item. + An image input to the model. Learn about [image inputs](/docs/guides/vision). - - `ApplyPatchCall object { id, call_id, operation, 4 more }` + - `ResponseInputFile object { type, detail, file_data, 4 more }` - A tool call that applies file diffs by creating, deleting, or updating files. + A file input to the model. - - `id: string` + - `version: optional string` - The unique ID of the apply patch tool call. Populated when this item is returned via API. + Optional version of the prompt template. - - `call_id: string` +- `prompt_cache_key: optional string` - The unique ID of the apply patch tool call generated by the model. + Used by OpenAI to cache responses for similar requests to optimize your cache hit rates. Replaces the `user` field. [Learn more](/docs/guides/prompt-caching). - - `operation: object { diff, path, type } or object { path, type } or object { diff, path, type }` +- `prompt_cache_options: optional object { mode, ttl }` - One of the create_file, delete_file, or update_file operations applied via apply_patch. + Options for prompt caching. Supported for `gpt-5.6` and later models. By default, OpenAI automatically chooses one implicit cache breakpoint. You can add explicit breakpoints to content blocks with `prompt_cache_breakpoint`. Each request can write up to four breakpoints. For cache matching, OpenAI considers up to the latest 80 breakpoints in the conversation, without a content-block lookback limit. Set `mode` to `explicit` to disable the implicit breakpoint. The `ttl` defaults to `30m`, which is currently the only supported value. See the [prompt caching guide](/docs/guides/prompt-caching) for current details. - - `CreateFile object { diff, path, type }` + - `mode: optional "implicit" or "explicit"` - Instruction describing how to create a file via the apply_patch tool. + Controls whether OpenAI automatically creates an implicit cache breakpoint. Defaults to `implicit`. With `implicit`, OpenAI creates one implicit breakpoint and writes up to the latest three explicit breakpoints in the request. With `explicit`, OpenAI does not create an implicit breakpoint and writes up to the latest four explicit breakpoints. If there are no explicit breakpoints, the request does not use prompt caching. - - `diff: string` + - `"implicit"` - Diff to apply. + - `"explicit"` - - `path: string` + - `ttl: optional "30m"` - Path of the file to create. + The minimum lifetime applied to every implicit and explicit cache breakpoint written by the request. Defaults to `30m`, which is currently the only supported value. The backend may retain cache entries for longer. - - `type: "create_file"` + - `"30m"` - Create a new file with the provided diff. +- `prompt_cache_retention: optional "in_memory" or "24h"` - - `"create_file"` + Deprecated. Use `prompt_cache_options.ttl` instead. - - `DeleteFile object { path, type }` + The retention policy for the prompt cache. Set to `24h` to enable extended prompt caching, which keeps cached prefixes active for longer, up to a maximum of 24 hours. [Learn more](/docs/guides/prompt-caching#prompt-cache-retention). + This field expresses a maximum retention policy, while + `prompt_cache_options.ttl` expresses a minimum cache lifetime. The two + fields are independent and do not interact. + For `gpt-5.5`, `gpt-5.5-pro`, and future models, only `24h` is supported. - Instruction describing how to delete a file via the apply_patch tool. + For older models that support both `in_memory` and `24h`, the default depends on your organization's data retention policy: - - `path: string` + - Organizations without ZDR enabled default to `24h`. + - Organizations with ZDR enabled default to `in_memory` when `prompt_cache_retention` is not specified. - Path of the file to delete. + - `"in_memory"` - - `type: "delete_file"` + - `"24h"` - Delete the specified file. +- `reasoning: optional Reasoning` - - `"delete_file"` + **gpt-5 and o-series models only** - - `UpdateFile object { diff, path, type }` + Configuration options for + [reasoning models](https://platform.openai.com/docs/guides/reasoning). - Instruction describing how to update a file via the apply_patch tool. + - `context: optional "auto" or "current_turn" or "all_turns"` - - `diff: string` + Controls which reasoning items are rendered back to the model on later turns. + If omitted or set to `auto`, the model determines the context mode. The + `gpt-5.6` model family defaults to `all_turns`; earlier models default to + `current_turn`. - Diff to apply. + When returned on a response, this is the effective reasoning context mode + used for the response. - - `path: string` + - `"auto"` - Path of the file to update. + - `"current_turn"` - - `type: "update_file"` + - `"all_turns"` - Update an existing file with the provided diff. + - `effort: optional ReasoningEffort` - - `"update_file"` + Constrains effort on reasoning for reasoning models. Currently supported + values are `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max`. + Reducing reasoning effort can result in faster responses and fewer tokens + used on reasoning in a response. Not all reasoning models support every + value. See the + [reasoning guide](https://platform.openai.com/docs/guides/reasoning) + for model-specific support. - - `status: "in_progress" or "completed"` + - `"none"` - The status of the apply patch tool call. One of `in_progress` or `completed`. + - `"minimal"` - - `"in_progress"` + - `"low"` - - `"completed"` + - `"medium"` - - `type: "apply_patch_call"` - - The type of the item. Always `apply_patch_call`. - - - `"apply_patch_call"` - - - `caller: optional object { type } or object { caller_id, type }` - - The execution context that produced this tool call. - - - `Direct object { type }` - - - `type: "direct"` - - - `"direct"` - - - `Program object { caller_id, type }` - - - `caller_id: string` - - The call ID of the program item that produced this tool call. - - - `type: "program"` - - - `"program"` - - - `created_by: optional string` - - The ID of the entity that created this tool call. - - - `ApplyPatchCallOutput object { id, call_id, status, 4 more }` - - The output emitted by an apply patch tool call. - - - `id: string` - - The unique ID of the apply patch tool call output. Populated when this item is returned via API. - - - `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"` - - - `caller: optional object { type } or object { caller_id, type }` - - The execution context that produced this tool call. - - - `Direct object { type }` - - - `type: "direct"` - - - `"direct"` - - - `Program object { caller_id, type }` - - - `caller_id: string` - - The call ID of the program item that produced this tool call. - - - `type: "program"` - - - `"program"` - - - `created_by: optional string` - - The ID of the entity that created this tool call output. - - - `output: optional string` - - Optional textual output returned by the apply patch tool. - - - `McpCall object { id, arguments, name, 6 more }` - - An invocation of a tool on an MCP server. - - - `id: string` - - The unique ID of the tool call. - - - `arguments: string` - - A JSON string of the arguments passed to the tool. - - - `name: string` - - The name of the tool that was run. - - - `server_label: string` - - The label of the MCP server running the tool. - - - `type: "mcp_call"` - - The type of the item. Always `mcp_call`. - - - `"mcp_call"` - - - `approval_request_id: optional string` - - Unique identifier for the MCP tool call approval request. - Include this value in a subsequent `mcp_approval_response` input to approve or reject the corresponding tool call. - - - `error: optional string` - - The error from the tool call, if any. - - - `output: optional string` - - The output from the tool call. + - `"high"` - - `status: optional "in_progress" or "completed" or "incomplete" or 2 more` + - `"xhigh"` - The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. + - `"max"` - - `"in_progress"` + - `generate_summary: optional "auto" or "concise" or "detailed"` - - `"completed"` + **Deprecated:** use `summary` instead. - - `"incomplete"` + A summary of the reasoning performed by the model. This can be + useful for debugging and understanding the model's reasoning process. + One of `auto`, `concise`, or `detailed`. - - `"calling"` + - `"auto"` - - `"failed"` + - `"concise"` - - `McpListTools object { id, server_label, tools, 2 more }` + - `"detailed"` - A list of tools available on an MCP server. + - `mode: optional string or "standard" or "pro"` - - `id: string` + Controls the reasoning execution mode for the request. - The unique ID of the list. + When returned on a response, this is the effective execution mode. - - `server_label: string` + - `string` - The label of the MCP server. + - `"standard" or "pro"` - - `tools: array of object { input_schema, name, annotations, description }` + Controls the reasoning execution mode for the request. - The tools available on the server. + When returned on a response, this is the effective execution mode. - - `input_schema: unknown` + - `"standard"` - The JSON schema describing the tool's input. + - `"pro"` - - `name: string` + - `summary: optional "auto" or "concise" or "detailed"` - The name of the tool. + A summary of the reasoning performed by the model. This can be + useful for debugging and understanding the model's reasoning process. + One of `auto`, `concise`, or `detailed`. - - `annotations: optional unknown` + `concise` is supported for `computer-use-preview` models and all reasoning models after `gpt-5`. - Additional annotations about the tool. + - `"auto"` - - `description: optional string` + - `"concise"` - The description of the tool. + - `"detailed"` - - `type: "mcp_list_tools"` +- `safety_identifier: optional string` - The type of the item. Always `mcp_list_tools`. + A stable identifier used to help detect users of your application that may be violating OpenAI's usage policies. + The IDs should be a string that uniquely identifies each user, with a maximum length of 64 characters. We recommend hashing their username or email address, in order to avoid sending us any identifying information. [Learn more](/docs/guides/safety-best-practices#safety-identifiers). - - `"mcp_list_tools"` +- `service_tier: optional "auto" or "default" or "flex" or 2 more` - - `error: optional string` + Specifies the processing type used for serving the request. - Error message if the server could not list tools. + - If set to 'auto', then the request will be processed with the service tier configured in the Project settings. Unless otherwise configured, the Project will use 'default'. + - If set to 'default', then the request will be processed with the standard pricing and performance for the selected model. + - If set to '[flex](/docs/guides/flex-processing)' or '[priority](https://openai.com/api-priority-processing/)', then the request will be processed with the corresponding service tier. + - When not set, the default behavior is 'auto'. - - `McpApprovalRequest object { id, arguments, name, 2 more }` + When the `service_tier` parameter is set, the response body will include the `service_tier` value based on the processing mode actually used to serve the request. This response value may be different from the value set in the parameter. - A request for human approval of a tool invocation. + - `"auto"` - - `id: string` + - `"default"` - The unique ID of the approval request. + - `"flex"` - - `arguments: string` + - `"scale"` - A JSON string of arguments for the tool. + - `"priority"` - - `name: string` +- `store: optional boolean` - The name of the tool to run. + Whether to store the generated model response for later retrieval via + API. - - `server_label: string` +- `stream: optional boolean` - The label of the MCP server making the request. + If set to true, the model response data will be streamed to the client + as it is generated using [server-sent events](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events/Using_server-sent_events#Event_stream_format). + See the [Streaming section below](/docs/api-reference/responses-streaming) + for more information. - - `type: "mcp_approval_request"` +- `stream_options: optional object { include_obfuscation }` - The type of the item. Always `mcp_approval_request`. + Options for streaming responses. Only set this when you set `stream: true`. - - `"mcp_approval_request"` + - `include_obfuscation: optional boolean` - - `McpApprovalResponse object { id, approval_request_id, approve, 2 more }` + When true, stream obfuscation will be enabled. Stream obfuscation adds + random characters to an `obfuscation` field on streaming delta events to + normalize payload sizes as a mitigation to certain side-channel attacks. + These obfuscation fields are included by default, but add a small amount + of overhead to the data stream. You can set `include_obfuscation` to + false to optimize for bandwidth if you trust the network links between + your application and the OpenAI API. - A response to an MCP approval request. +- `temperature: optional number` - - `id: string` + What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. + We generally recommend altering this or `top_p` but not both. - The unique ID of the approval response +- `text: optional ResponseTextConfig` - - `approval_request_id: string` + Configuration options for a text response from the model. Can be plain + text or structured JSON data. Learn more: - The ID of the approval request being answered. + - [Text inputs and outputs](/docs/guides/text) + - [Structured Outputs](/docs/guides/structured-outputs) - - `approve: boolean` + - `format: optional ResponseFormatTextConfig` - Whether the request was approved. + An object specifying the format that the model must output. - - `type: "mcp_approval_response"` + Configuring `{ "type": "json_schema" }` enables Structured Outputs, + which ensures the model will match your supplied JSON schema. Learn more in the + [Structured Outputs guide](/docs/guides/structured-outputs). - The type of the item. Always `mcp_approval_response`. + The default format is `{ "type": "text" }` with no additional options. - - `"mcp_approval_response"` + **Not recommended for gpt-4o and newer models:** - - `reason: optional string` + Setting to `{ "type": "json_object" }` enables the older JSON mode, which + ensures the message the model generates is valid JSON. Using `json_schema` + is preferred for models that support it. - Optional reason for the decision. + - `ResponseFormatText object { type }` - - `CustomToolCall object { call_id, input, name, 4 more }` + Default response format. Used to generate text responses. - A call to a custom tool created by the model. + - `type: "text"` - - `call_id: string` + The type of response format being defined. Always `text`. - An identifier used to map this custom tool call to a tool call output. + - `"text"` - - `input: string` + - `ResponseFormatTextJSONSchemaConfig object { name, schema, type, 2 more }` - The input for the custom tool call generated by the model. + JSON Schema response format. Used to generate structured JSON responses. + Learn more about [Structured Outputs](/docs/guides/structured-outputs). - `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. - - - `caller: optional object { type } or object { caller_id, type }` - - The execution context that produced this tool call. - - - `Direct object { type }` - - - `type: "direct"` - - - `"direct"` - - - `Program object { caller_id, type }` - - - `caller_id: string` - - The call ID of the program item that produced this tool call. - - - `type: "program"` - - - `"program"` - - - `namespace: optional string` - - The namespace of the custom tool being called. - - - `CustomToolCallOutput object { id, call_id, output, 4 more }` - - - `id: string` - - The unique ID of the custom tool call output item. - - - `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, prompt_cache_breakpoint }` - - A text input to the model. - - - `ResponseInputImage object { detail, type, file_id, 2 more }` - - An image input to the model. Learn about [image inputs](/docs/guides/vision). - - - `ResponseInputFile object { type, detail, file_data, 4 more }` - - A file input to the model. - - - `status: "in_progress" or "completed" or "incomplete"` - - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. - - - `"in_progress"` - - - `"completed"` - - - `"incomplete"` - - - `type: "custom_tool_call_output"` - - The type of the custom tool call output. Always `custom_tool_call_output`. + The name of the response format. Must be a-z, A-Z, 0-9, or contain + underscores and dashes, with a maximum length of 64. - - `"custom_tool_call_output"` + - `schema: map[unknown]` - - `caller: optional object { type } or object { caller_id, type }` + The schema for the response format, described as a JSON Schema object. + Learn how to build JSON schemas [here](https://json-schema.org/). - The execution context that produced this tool call. + - `type: "json_schema"` - - `Direct object { type }` + The type of response format being defined. Always `json_schema`. - - `type: "direct"` + - `"json_schema"` - The caller type. Always `direct`. + - `description: optional string` - - `"direct"` + A description of what the response format is for, used by the model to + determine how to respond in the format. - - `Program object { caller_id, type }` + - `strict: optional boolean` - - `caller_id: string` + Whether to enable strict schema adherence when generating the output. + If set to true, the model will always follow the exact schema defined + in the `schema` field. Only a subset of JSON Schema is supported when + `strict` is `true`. To learn more, read the [Structured Outputs + guide](/docs/guides/structured-outputs). - The call ID of the program item that produced this tool call. + - `ResponseFormatJSONObject object { type }` - - `type: "program"` + JSON object response format. An older method of generating JSON responses. + Using `json_schema` is recommended for models that support it. Note that the + model will not generate JSON without a system or user message instructing it + to do so. - The caller type. Always `program`. + - `type: "json_object"` - - `"program"` + The type of response format being defined. Always `json_object`. - - `created_by: optional string` + - `"json_object"` - The identifier of the actor that created the item. + - `verbosity: optional "low" or "medium" or "high"` - - `parallel_tool_calls: boolean` + Constrains the verbosity of the model's response. Lower values will result in + more concise responses, while higher values will result in more verbose responses. + Currently supported values are `low`, `medium`, and `high`. The default is + `medium`. - Whether to allow the model to run tool calls in parallel. + - `"low"` - - `temperature: number` + - `"medium"` - What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. - We generally recommend altering this or `top_p` but not both. + - `"high"` - - `tool_choice: ToolChoiceOptions or ToolChoiceAllowed or ToolChoiceTypes or 6 more` +- `tool_choice: optional ToolChoiceOptions or ToolChoiceAllowed or ToolChoiceTypes or 6 more` How the model should select which tool (or tools) to use when generating a response. See the `tools` parameter to see how to specify which tools @@ -23395,7 +22594,7 @@ Retrieves a model response with the given ID. - `"shell"` - - `tools: array of object { name, parameters, strict, 5 more } or object { type, vector_store_ids, filters, 2 more } or object { type } or 13 more` +- `tools: optional array of object { name, parameters, strict, 5 more } or object { type, vector_store_ids, filters, 2 more } or object { type } or 13 more` An array of tools the model may call while generating a response. You can specify which tool to use by setting the `tool_choice` parameter. @@ -24224,7 +23423,14 @@ Retrieves a model response with the given ID. - `"programmatic"` - - `top_p: number` +- `top_logprobs: optional number` + + An integer between 0 and 20 specifying the maximum number of most likely + tokens to return at each token position, each with an associated log + probability. In some cases, the number of returned tokens may be fewer than + requested. + +- `top_p: optional number` An alternative to sampling with temperature, called nucleus sampling, where the model considers the results of the tokens with top_p probability @@ -24233,1492 +23439,691 @@ Retrieves a model response with the given ID. We generally recommend altering this or `temperature` but not both. - - `background: optional boolean` +- `truncation: optional "auto" or "disabled"` - Whether to run the model response in the background. - [Learn more](/docs/guides/background). + The truncation strategy to use for the model response. - - `completed_at: optional number` + - `auto`: If the input to this Response exceeds + the model's context window size, the model will truncate the + response to fit the context window by dropping items from the beginning of the conversation. + - `disabled` (default): If the input size will exceed the context window + size for a model, the request will fail with a 400 error. - Unix timestamp (in seconds) of when this Response was completed. - Only present when the status is `completed`. + - `"auto"` - - `conversation: optional object { id }` + - `"disabled"` - The conversation that this response belonged to. Input items and output items from this response were automatically added to this conversation. +- `user: optional string` - - `id: string` + This field is being replaced by `safety_identifier` and `prompt_cache_key`. Use `prompt_cache_key` instead to maintain caching optimizations. + A stable identifier for your end-users. + Used to boost cache hit rates by better bucketing similar requests and to help OpenAI detect and prevent abuse. [Learn more](/docs/guides/safety-best-practices#safety-identifiers). - The unique ID of the conversation that this response was associated with. +### Returns - - `max_output_tokens: optional number` +- `Response object { id, created_at, error, 32 more }` - An upper bound for the number of tokens that can be generated for a response, including visible output tokens and [reasoning tokens](/docs/guides/reasoning). + - `id: string` - - `max_tool_calls: optional number` + Unique identifier for this Response. - The maximum number of total calls to built-in tools that can be processed in a response. This maximum number applies across all built-in tool calls, not per individual tool. Any further attempts to call a tool by the model will be ignored. + - `created_at: number` - - `moderation: optional object { input, output }` + Unix timestamp (in seconds) of when this Response was created. - Moderation results for the response input and output, if moderated completions were requested. + - `error: ResponseError` - - `input: object { categories, category_applied_input_types, category_scores, 3 more } or object { code, message, type }` + An error object returned when the model fails to generate a Response. - Moderation for the response input. + - `code: "server_error" or "rate_limit_exceeded" or "invalid_prompt" or 17 more` - - `ModerationResult object { categories, category_applied_input_types, category_scores, 3 more }` + The error code for the response. - A moderation result produced for the response input or output. + - `"server_error"` - - `categories: map[boolean]` + - `"rate_limit_exceeded"` - A dictionary of moderation categories to booleans, True if the input is flagged under this category. + - `"invalid_prompt"` - - `category_applied_input_types: map[array of "text" or "image"]` + - `"data_residency_mismatch"` - Which modalities of input are reflected by the score for each category. + - `"bio_policy"` - - `"text"` + - `"vector_store_timeout"` - - `"image"` + - `"invalid_image"` - - `category_scores: map[number]` + - `"invalid_image_format"` - A dictionary of moderation categories to scores. + - `"invalid_base64_image"` - - `flagged: boolean` + - `"invalid_image_url"` - A boolean indicating whether the content was flagged by any category. + - `"image_too_large"` - - `model: string` + - `"image_too_small"` - The moderation model that produced this result. + - `"image_parse_error"` - - `type: "moderation_result"` + - `"image_content_policy_violation"` - The object type, which was always `moderation_result` for successful moderation results. + - `"invalid_image_mode"` - - `"moderation_result"` + - `"image_file_too_large"` - - `Error object { code, message, type }` + - `"unsupported_image_media_type"` - An error produced while attempting moderation for the response input or output. + - `"empty_image_file"` - - `code: string` + - `"failed_to_download_image"` - The error code. + - `"image_file_not_found"` - `message: string` - The error message. + A human-readable description of the error. - - `type: "error"` + - `incomplete_details: object { reason }` - The object type, which was always `error` for moderation failures. + Details about why the response is incomplete. - - `"error"` + - `reason: optional "max_output_tokens" or "content_filter"` - - `output: object { categories, category_applied_input_types, category_scores, 3 more } or object { code, message, type }` + The reason why the response is incomplete. - Moderation for the response output. + - `"max_output_tokens"` - - `ModerationResult object { categories, category_applied_input_types, category_scores, 3 more }` + - `"content_filter"` - A moderation result produced for the response input or output. + - `instructions: string or array of EasyInputMessage or object { content, role, status, type } or ResponseOutputMessage or 29 more` - - `categories: map[boolean]` + A system (or developer) message inserted into the model's context. - A dictionary of moderation categories to booleans, True if the input is flagged under this category. + When using along with `previous_response_id`, the instructions from a previous + response will not be carried over to the next response. This makes it simple + to swap out system (or developer) messages in new responses. - - `category_applied_input_types: map[array of "text" or "image"]` + - `string` - Which modalities of input are reflected by the score for each category. + A text input to the model, equivalent to a text input with the + `developer` role. - - `"text"` + - `InputItemList = array of EasyInputMessage or object { content, role, status, type } or ResponseOutputMessage or 29 more` - - `"image"` + A list of one or many input items to the model, containing + different content types. - - `category_scores: map[number]` + - `EasyInputMessage object { content, role, phase, type }` - A dictionary of moderation categories to scores. + 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. - - `flagged: boolean` + - `content: string or ResponseInputMessageContentList` - A boolean indicating whether the content was flagged by any category. + Text, image, or audio input to the model, used to generate a response. + Can also contain previous assistant responses. - - `model: string` + - `TextInput = string` - The moderation model that produced this result. + A text input to the model. - - `type: "moderation_result"` + - `ResponseInputMessageContentList = array of ResponseInputContent` - The object type, which was always `moderation_result` for successful moderation results. + A list of one or many input items to the model, containing different content + types. - - `"moderation_result"` + - `ResponseInputText object { text, type, prompt_cache_breakpoint }` - - `Error object { code, message, type }` + A text input to the model. - An error produced while attempting moderation for the response input or output. + - `text: string` - - `code: string` + The text input to the model. - The error code. + - `type: "input_text"` - - `message: string` + The type of the input item. Always `input_text`. - The error message. + - `"input_text"` - - `type: "error"` + - `prompt_cache_breakpoint: optional object { mode }` - The object type, which was always `error` for moderation failures. + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - `"error"` + - `mode: "explicit"` - - `output_text: optional string` + The breakpoint mode. Always `explicit`. - SDK-only convenience property that contains the aggregated text output - from all `output_text` items in the `output` array, if any are present. - Supported in the Python and JavaScript SDKs. + - `"explicit"` - - `previous_response_id: optional string` + - `ResponseInputImage object { detail, type, file_id, 2 more }` - The unique ID of the previous response to the model. Use this to - create multi-turn conversations. Learn more about - [conversation state](/docs/guides/conversation-state). Cannot be used in conjunction with `conversation`. + An image input to the model. Learn about [image inputs](/docs/guides/vision). - - `prompt: optional ResponsePrompt` + - `detail: "low" or "high" or "auto" or "original"` - Reference to a prompt template and its variables. - [Learn more](/docs/guides/text?api-mode=responses#reusable-prompts). + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - - `id: string` + - `"low"` - The unique identifier of the prompt template to use. + - `"high"` - - `variables: optional map[string or ResponseInputText or ResponseInputImage or ResponseInputFile]` + - `"auto"` - Optional map of values to substitute in for variables in your - prompt. The substitution values can either be strings, or other - Response input types like images or files. + - `"original"` - - `string` + - `type: "input_image"` - - `ResponseInputText object { text, type, prompt_cache_breakpoint }` + The type of the input item. Always `input_image`. - A text input to the model. + - `"input_image"` - - `ResponseInputImage object { detail, type, file_id, 2 more }` + - `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, 4 more }` + - `image_url: optional string` - A file input to the model. + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - - `version: optional string` + - `prompt_cache_breakpoint: optional object { mode }` - Optional version of the prompt template. + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - `prompt_cache_key: optional string` + - `mode: "explicit"` - Used by OpenAI to cache responses for similar requests to optimize your cache hit rates. Replaces the `user` field. [Learn more](/docs/guides/prompt-caching). + The breakpoint mode. Always `explicit`. - - `prompt_cache_options: optional object { mode, ttl }` + - `"explicit"` - The prompt-caching options that were applied to the response. Supported for `gpt-5.6` and later models. + - `ResponseInputFile object { type, detail, file_data, 4 more }` - - `mode: "implicit" or "explicit"` + A file input to the model. - Whether implicit prompt-cache breakpoints were enabled. + - `type: "input_file"` - - `"implicit"` + The type of the input item. Always `input_file`. - - `"explicit"` + - `"input_file"` - - `ttl: "30m"` + - `detail: optional "auto" or "low" or "high"` - The minimum lifetime applied to each cache breakpoint. + The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. - - `"30m"` + - `"auto"` - - `prompt_cache_retention: optional "in_memory" or "24h"` + - `"low"` - Deprecated. Use `prompt_cache_options.ttl` instead. + - `"high"` - The retention policy for the prompt cache. Set to `24h` to enable extended prompt caching, which keeps cached prefixes active for longer, up to a maximum of 24 hours. [Learn more](/docs/guides/prompt-caching#prompt-cache-retention). - This field expresses a maximum retention policy, while - `prompt_cache_options.ttl` expresses a minimum cache lifetime. The two - fields are independent and do not interact. - For `gpt-5.5`, `gpt-5.5-pro`, and future models, only `24h` is supported. + - `file_data: optional string` - For older models that support both `in_memory` and `24h`, the default depends on your organization's data retention policy: + The content of the file to be sent to the model. - - Organizations without ZDR enabled default to `24h`. - - Organizations with ZDR enabled default to `in_memory` when `prompt_cache_retention` is not specified. + - `file_id: optional string` - - `"in_memory"` + The ID of the file to be sent to the model. - - `"24h"` + - `file_url: optional string` - - `reasoning: optional Reasoning` + The URL of the file to be sent to the model. - **gpt-5 and o-series models only** + - `filename: optional string` - Configuration options for - [reasoning models](https://platform.openai.com/docs/guides/reasoning). + The name of the file to be sent to the model. - - `context: optional "auto" or "current_turn" or "all_turns"` + - `prompt_cache_breakpoint: optional object { mode }` - Controls which reasoning items are rendered back to the model on later turns. - If omitted or set to `auto`, the model determines the context mode. The - `gpt-5.6` model family defaults to `all_turns`; earlier models default to - `current_turn`. + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - When returned on a response, this is the effective reasoning context mode - used for the response. + - `mode: "explicit"` - - `"auto"` + The breakpoint mode. Always `explicit`. - - `"current_turn"` + - `"explicit"` - - `"all_turns"` + - `role: "user" or "assistant" or "system" or "developer"` - - `effort: optional ReasoningEffort` + The role of the message input. One of `user`, `assistant`, `system`, or + `developer`. - Constrains effort on reasoning for reasoning models. Currently supported - values are `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max`. - Reducing reasoning effort can result in faster responses and fewer tokens - used on reasoning in a response. Not all reasoning models support every - value. See the - [reasoning guide](https://platform.openai.com/docs/guides/reasoning) - for model-specific support. + - `"user"` - - `"none"` + - `"assistant"` - - `"minimal"` + - `"system"` - - `"low"` + - `"developer"` - - `"medium"` + - `phase: optional "commentary" or "final_answer"` - - `"high"` + 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. - - `"xhigh"` + - `"commentary"` - - `"max"` + - `"final_answer"` - - `generate_summary: optional "auto" or "concise" or "detailed"` + - `type: optional "message"` - **Deprecated:** use `summary` instead. + The type of the message input. Always `message`. - A summary of the reasoning performed by the model. This can be - useful for debugging and understanding the model's reasoning process. - One of `auto`, `concise`, or `detailed`. + - `"message"` - - `"auto"` + - `Message object { content, role, status, type }` - - `"concise"` + 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. - - `"detailed"` + - `content: ResponseInputMessageContentList` - - `mode: optional string or "standard" or "pro"` + A list of one or many input items to the model, containing different content + types. - Controls the reasoning execution mode for the request. + - `role: "user" or "system" or "developer"` - When returned on a response, this is the effective execution mode. + The role of the message input. One of `user`, `system`, or `developer`. - - `string` + - `"user"` - - `"standard" or "pro"` + - `"system"` - Controls the reasoning execution mode for the request. + - `"developer"` - When returned on a response, this is the effective execution mode. + - `status: optional "in_progress" or "completed" or "incomplete"` - - `"standard"` + The status of item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `"pro"` + - `"in_progress"` - - `summary: optional "auto" or "concise" or "detailed"` + - `"completed"` - A summary of the reasoning performed by the model. This can be - useful for debugging and understanding the model's reasoning process. - One of `auto`, `concise`, or `detailed`. + - `"incomplete"` - `concise` is supported for `computer-use-preview` models and all reasoning models after `gpt-5`. + - `type: optional "message"` - - `"auto"` + The type of the message input. Always set to `message`. - - `"concise"` + - `"message"` - - `"detailed"` + - `ResponseOutputMessage object { id, content, role, 3 more }` - - `safety_identifier: optional string` + An output message from the model. - A stable identifier used to help detect users of your application that may be violating OpenAI's usage policies. - The IDs should be a string that uniquely identifies each user, with a maximum length of 64 characters. We recommend hashing their username or email address, in order to avoid sending us any identifying information. [Learn more](/docs/guides/safety-best-practices#safety-identifiers). + - `id: string` - - `service_tier: optional "auto" or "default" or "flex" or 2 more` + The unique ID of the output message. - Specifies the processing type used for serving the request. + - `content: array of ResponseOutputText or ResponseOutputRefusal` - - If set to 'auto', then the request will be processed with the service tier configured in the Project settings. Unless otherwise configured, the Project will use 'default'. - - If set to 'default', then the request will be processed with the standard pricing and performance for the selected model. - - If set to '[flex](/docs/guides/flex-processing)' or '[priority](https://openai.com/api-priority-processing/)', then the request will be processed with the corresponding service tier. - - When not set, the default behavior is 'auto'. + The content of the output message. - When the `service_tier` parameter is set, the response body will include the `service_tier` value based on the processing mode actually used to serve the request. This response value may be different from the value set in the parameter. + - `ResponseOutputText object { annotations, logprobs, text, type }` - - `"auto"` + A text output from the model. - - `"default"` + - `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 }` - - `"flex"` + The annotations of the text output. - - `"scale"` + - `FileCitation object { file_id, filename, index, type }` - - `"priority"` + A citation to a file. - - `status: optional ResponseStatus` + - `file_id: string` - The status of the response generation. One of `completed`, `failed`, - `in_progress`, `cancelled`, `queued`, or `incomplete`. + The ID of the file. - - `"completed"` + - `filename: string` - - `"failed"` + The filename of the file cited. - - `"in_progress"` + - `index: number` - - `"cancelled"` + The index of the file in the list of files. - - `"queued"` + - `type: "file_citation"` - - `"incomplete"` + The type of the file citation. Always `file_citation`. - - `text: optional ResponseTextConfig` + - `"file_citation"` - Configuration options for a text response from the model. Can be plain - text or structured JSON data. Learn more: + - `URLCitation object { end_index, start_index, title, 2 more }` - - [Text inputs and outputs](/docs/guides/text) - - [Structured Outputs](/docs/guides/structured-outputs) + A citation for a web resource used to generate a model response. - - `format: optional ResponseFormatTextConfig` + - `end_index: number` - An object specifying the format that the model must output. + The index of the last character of the URL citation in the message. - Configuring `{ "type": "json_schema" }` enables Structured Outputs, - which ensures the model will match your supplied JSON schema. Learn more in the - [Structured Outputs guide](/docs/guides/structured-outputs). + - `start_index: number` - The default format is `{ "type": "text" }` with no additional options. + The index of the first character of the URL citation in the message. - **Not recommended for gpt-4o and newer models:** + - `title: string` - Setting to `{ "type": "json_object" }` enables the older JSON mode, which - ensures the message the model generates is valid JSON. Using `json_schema` - is preferred for models that support it. + The title of the web resource. - - `ResponseFormatText object { type }` + - `type: "url_citation"` - Default response format. Used to generate text responses. + The type of the URL citation. Always `url_citation`. - - `type: "text"` + - `"url_citation"` - The type of response format being defined. Always `text`. + - `url: string` - - `"text"` + The URL of the web resource. - - `ResponseFormatTextJSONSchemaConfig object { name, schema, type, 2 more }` + - `ContainerFileCitation object { container_id, end_index, file_id, 3 more }` - JSON Schema response format. Used to generate structured JSON responses. - Learn more about [Structured Outputs](/docs/guides/structured-outputs). + A citation for a container file used to generate a model response. - - `name: string` + - `container_id: string` - The name of the response format. Must be a-z, A-Z, 0-9, or contain - underscores and dashes, with a maximum length of 64. + The ID of the container file. - - `schema: map[unknown]` + - `end_index: number` - The schema for the response format, described as a JSON Schema object. - Learn how to build JSON schemas [here](https://json-schema.org/). + The index of the last character of the container file citation in the message. - - `type: "json_schema"` + - `file_id: string` - The type of response format being defined. Always `json_schema`. + The ID of the file. - - `"json_schema"` + - `filename: string` - - `description: optional string` + The filename of the container file cited. - A description of what the response format is for, used by the model to - determine how to respond in the format. + - `start_index: number` - - `strict: optional boolean` + The index of the first character of the container file citation in the message. - Whether to enable strict schema adherence when generating the output. - If set to true, the model will always follow the exact schema defined - in the `schema` field. Only a subset of JSON Schema is supported when - `strict` is `true`. To learn more, read the [Structured Outputs - guide](/docs/guides/structured-outputs). + - `type: "container_file_citation"` - - `ResponseFormatJSONObject object { type }` + The type of the container file citation. Always `container_file_citation`. - JSON object response format. An older method of generating JSON responses. - Using `json_schema` is recommended for models that support it. Note that the - model will not generate JSON without a system or user message instructing it - to do so. + - `"container_file_citation"` - - `type: "json_object"` + - `FilePath object { file_id, index, type }` - The type of response format being defined. Always `json_object`. + A path to a file. - - `"json_object"` + - `file_id: string` - - `verbosity: optional "low" or "medium" or "high"` + The ID of the file. - Constrains the verbosity of the model's response. Lower values will result in - more concise responses, while higher values will result in more verbose responses. - Currently supported values are `low`, `medium`, and `high`. The default is - `medium`. + - `index: number` - - `"low"` + The index of the file in the list of files. - - `"medium"` + - `type: "file_path"` - - `"high"` + The type of the file path. Always `file_path`. - - `top_logprobs: optional number` + - `"file_path"` - An integer between 0 and 20 specifying the maximum number of most likely - tokens to return at each token position, each with an associated log - probability. In some cases, the number of returned tokens may be fewer than - requested. + - `logprobs: array of object { token, bytes, logprob, top_logprobs }` - - `truncation: optional "auto" or "disabled"` + - `token: string` - The truncation strategy to use for the model response. + - `bytes: array of number` - - `auto`: If the input to this Response exceeds - the model's context window size, the model will truncate the - response to fit the context window by dropping items from the beginning of the conversation. - - `disabled` (default): If the input size will exceed the context window - size for a model, the request will fail with a 400 error. + - `logprob: number` - - `"auto"` + - `top_logprobs: array of object { token, bytes, logprob }` - - `"disabled"` + - `token: string` - - `usage: optional ResponseUsage` + - `bytes: array of number` - Represents token usage details including input tokens, output tokens, - a breakdown of output tokens, and the total tokens used. - - - `input_tokens: number` - - The number of input tokens. - - - `input_tokens_details: object { cache_write_tokens, cached_tokens }` + - `logprob: number` - A detailed breakdown of the input tokens. + - `text: string` - - `cache_write_tokens: number` + The text output from the model. - The number of input tokens that were written to the cache. + - `type: "output_text"` - - `cached_tokens: number` + The type of the output text. Always `output_text`. - The number of tokens that were retrieved from the cache. - [More on prompt caching](/docs/guides/prompt-caching). + - `"output_text"` - - `output_tokens: number` + - `ResponseOutputRefusal object { refusal, type }` - The number of output tokens. + A refusal from the model. - - `output_tokens_details: object { reasoning_tokens }` + - `refusal: string` - A detailed breakdown of the output tokens. + The refusal explanation from the model. - - `reasoning_tokens: number` + - `type: "refusal"` - The number of reasoning tokens. + The type of the refusal. Always `refusal`. - - `total_tokens: number` + - `"refusal"` - The total number of tokens used. + - `role: "assistant"` - - `user: optional string` + The role of the output message. Always `assistant`. - This field is being replaced by `safety_identifier` and `prompt_cache_key`. Use `prompt_cache_key` instead to maintain caching optimizations. - A stable identifier for your end-users. - Used to boost cache hit rates by better bucketing similar requests and to help OpenAI detect and prevent abuse. [Learn more](/docs/guides/safety-best-practices#safety-identifiers). + - `"assistant"` -### Example + - `status: "in_progress" or "completed" or "incomplete"` -```http -curl https://api.openai.com/v1/responses/$RESPONSE_ID \ - -H "Authorization: Bearer $OPENAI_API_KEY" -``` + The status of the message input. One of `in_progress`, `completed`, or + `incomplete`. Populated when input items are returned via API. -#### Response + - `"in_progress"` -```json -{ - "id": "id", - "created_at": 0, - "error": { - "code": "server_error", - "message": "message" - }, - "incomplete_details": { - "reason": "max_output_tokens" - }, - "instructions": "string", - "metadata": { - "foo": "string" - }, - "model": "gpt-5.1", - "object": "response", - "output": [ - { - "id": "id", - "content": [ - { - "annotations": [ - { - "file_id": "file_id", - "filename": "filename", - "index": 0, - "type": "file_citation" - } - ], - "logprobs": [ - { - "token": "token", - "bytes": [ - 0 - ], - "logprob": 0, - "top_logprobs": [ - { - "token": "token", - "bytes": [ - 0 - ], - "logprob": 0 - } - ] - } - ], - "text": "text", - "type": "output_text" - } - ], - "role": "assistant", - "status": "in_progress", - "type": "message", - "phase": "commentary" - } - ], - "parallel_tool_calls": true, - "temperature": 1, - "tool_choice": "none", - "tools": [ - { - "name": "name", - "parameters": { - "foo": "bar" - }, - "strict": true, - "type": "function", - "allowed_callers": [ - "direct" - ], - "defer_loading": true, - "description": "description", - "output_schema": { - "foo": "bar" - } - } - ], - "top_p": 1, - "background": true, - "completed_at": 0, - "conversation": { - "id": "id" - }, - "max_output_tokens": 0, - "max_tool_calls": 0, - "moderation": { - "input": { - "categories": { - "foo": true - }, - "category_applied_input_types": { - "foo": [ - "text" - ] - }, - "category_scores": { - "foo": 0 - }, - "flagged": true, - "model": "model", - "type": "moderation_result" - }, - "output": { - "categories": { - "foo": true - }, - "category_applied_input_types": { - "foo": [ - "text" - ] - }, - "category_scores": { - "foo": 0 - }, - "flagged": true, - "model": "model", - "type": "moderation_result" - } - }, - "output_text": "output_text", - "previous_response_id": "previous_response_id", - "prompt": { - "id": "id", - "variables": { - "foo": "string" - }, - "version": "version" - }, - "prompt_cache_key": "prompt-cache-key-1234", - "prompt_cache_options": { - "mode": "implicit", - "ttl": "30m" - }, - "prompt_cache_retention": "in_memory", - "reasoning": { - "context": "auto", - "effort": "none", - "generate_summary": "auto", - "mode": "standard", - "summary": "auto" - }, - "safety_identifier": "safety-identifier-1234", - "service_tier": "auto", - "status": "completed", - "text": { - "format": { - "type": "text" - }, - "verbosity": "low" - }, - "top_logprobs": 0, - "truncation": "auto", - "usage": { - "input_tokens": 0, - "input_tokens_details": { - "cache_write_tokens": 0, - "cached_tokens": 0 - }, - "output_tokens": 0, - "output_tokens_details": { - "reasoning_tokens": 0 - }, - "total_tokens": 0 - }, - "user": "user-1234" -} -``` + - `"completed"` -### Example + - `"incomplete"` -```http -curl https://api.openai.com/v1/responses/resp_123 \ - -H "Content-Type: application/json" \ - -H "Authorization: Bearer $OPENAI_API_KEY" -``` + - `type: "message"` -#### Response + The type of the output message. Always `message`. -```json -{ - "id": "resp_67cb71b351908190a308f3859487620d06981a8637e6bc44", - "object": "response", - "created_at": 1741386163, - "status": "completed", - "completed_at": 1741386164, - "error": null, - "incomplete_details": null, - "instructions": null, - "max_output_tokens": null, - "model": "gpt-4o-2024-08-06", - "output": [ - { - "type": "message", - "id": "msg_67cb71b3c2b0819084d481baaaf148f206981a8637e6bc44", - "status": "completed", - "role": "assistant", - "content": [ - { - "type": "output_text", - "text": "Silent circuits hum, \nThoughts emerge in data streams— \nDigital dawn breaks.", - "annotations": [] - } - ] - } - ], - "parallel_tool_calls": true, - "previous_response_id": null, - "reasoning": { - "effort": null, - "summary": null - }, - "store": true, - "temperature": 1.0, - "text": { - "format": { - "type": "text" - } - }, - "tool_choice": "auto", - "tools": [], - "top_p": 1.0, - "truncation": "disabled", - "usage": { - "input_tokens": 32, - "input_tokens_details": { - "cached_tokens": 0, - "cache_write_tokens": 0 - }, - "output_tokens": 18, - "output_tokens_details": { - "reasoning_tokens": 0 - }, - "total_tokens": 50 - }, - "user": null, - "metadata": {} -} -``` + - `"message"` -## Delete a model response + - `phase: optional "commentary" or "final_answer"` -**delete** `/responses/{response_id}` + 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. -Deletes a model response with the given ID. + - `"commentary"` -### Path Parameters + - `"final_answer"` -- `response_id: string` + - `FileSearchCall object { id, queries, status, 2 more }` -### Example + The results of a file search tool call. See the + [file search guide](/docs/guides/tools-file-search) for more information. -```http -curl https://api.openai.com/v1/responses/$RESPONSE_ID \ - -X DELETE \ - -H "Authorization: Bearer $OPENAI_API_KEY" -``` + - `id: string` -### Example + The unique ID of the file search tool call. -```http -curl -X DELETE https://api.openai.com/v1/responses/resp_123 \ - -H "Content-Type: application/json" \ - -H "Authorization: Bearer $OPENAI_API_KEY" -``` + - `queries: array of string` -#### Response + The queries used to search for files. -```json -{ - "id": "resp_6786a1bec27481909a17d673315b29f6", - "object": "response", - "deleted": true -} -``` + - `status: "in_progress" or "searching" or "completed" or 2 more` -## Cancel a response + The status of the file search tool call. One of `in_progress`, + `searching`, `incomplete` or `failed`, -**post** `/responses/{response_id}/cancel` + - `"in_progress"` -Cancels a model response with the given ID. Only responses created with -the `background` parameter set to `true` can be cancelled. -[Learn more](/docs/guides/background). + - `"searching"` -### Path Parameters + - `"completed"` -- `response_id: string` + - `"incomplete"` -### Returns + - `"failed"` -- `Response object { id, created_at, error, 32 more }` + - `type: "file_search_call"` - - `id: string` + The type of the file search tool call. Always `file_search_call`. - Unique identifier for this Response. + - `"file_search_call"` - - `created_at: number` + - `results: optional array of object { attributes, file_id, filename, 2 more }` - Unix timestamp (in seconds) of when this Response was created. + The results of the file search tool call. - - `error: ResponseError` + - `attributes: optional map[string or number or boolean]` - An error object returned when the model fails to generate a Response. + 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. - - `code: "server_error" or "rate_limit_exceeded" or "invalid_prompt" or 17 more` + - `string` - The error code for the response. + - `number` - - `"server_error"` + - `boolean` - - `"rate_limit_exceeded"` + - `file_id: optional string` - - `"invalid_prompt"` + The unique ID of the file. - - `"data_residency_mismatch"` + - `filename: optional string` - - `"bio_policy"` + The name of the file. - - `"vector_store_timeout"` + - `score: optional number` - - `"invalid_image"` + The relevance score of the file - a value between 0 and 1. - - `"invalid_image_format"` + - `text: optional string` - - `"invalid_base64_image"` + The text that was retrieved from the file. - - `"invalid_image_url"` + - `ComputerCall object { id, call_id, pending_safety_checks, 4 more }` - - `"image_too_large"` + A tool call to a computer use tool. See the + [computer use guide](/docs/guides/tools-computer-use) for more information. - - `"image_too_small"` + - `id: string` - - `"image_parse_error"` + The unique ID of the computer call. - - `"image_content_policy_violation"` + - `call_id: string` - - `"invalid_image_mode"` + An identifier used when responding to the tool call with output. - - `"image_file_too_large"` + - `pending_safety_checks: array of object { id, code, message }` - - `"unsupported_image_media_type"` + The pending safety checks for the computer call. - - `"empty_image_file"` + - `id: string` - - `"failed_to_download_image"` + The ID of the pending safety check. - - `"image_file_not_found"` + - `code: optional string` - - `message: string` + The type of the pending safety check. - A human-readable description of the error. + - `message: optional string` - - `incomplete_details: object { reason }` + Details about the pending safety check. - Details about why the response is incomplete. + - `status: "in_progress" or "completed" or "incomplete"` - - `reason: optional "max_output_tokens" or "content_filter"` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - The reason why the response is incomplete. + - `"in_progress"` - - `"max_output_tokens"` + - `"completed"` - - `"content_filter"` + - `"incomplete"` - - `instructions: string or array of EasyInputMessage or object { content, role, status, type } or ResponseOutputMessage or 29 more` + - `type: "computer_call"` - A system (or developer) message inserted into the model's context. + The type of the computer call. Always `computer_call`. - When using along with `previous_response_id`, the instructions from a previous - response will not be carried over to the next response. This makes it simple - to swap out system (or developer) messages in new responses. + - `"computer_call"` - - `string` + - `action: optional ComputerAction` - A text input to the model, equivalent to a text input with the - `developer` role. + A click action. - - `InputItemList = array of EasyInputMessage or object { content, role, status, type } or ResponseOutputMessage or 29 more` + - `Click object { button, type, x, 2 more }` - A list of one or many input items to the model, containing - different content types. + A click action. - - `EasyInputMessage object { content, role, phase, type }` + - `button: "left" or "right" or "wheel" or 2 more` - 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. + Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. - - `content: string or ResponseInputMessageContentList` + - `"left"` - Text, image, or audio input to the model, used to generate a response. - Can also contain previous assistant responses. + - `"right"` - - `TextInput = string` + - `"wheel"` - A text input to the model. + - `"back"` - - `ResponseInputMessageContentList = array of ResponseInputContent` + - `"forward"` - A list of one or many input items to the model, containing different content - types. + - `type: "click"` - - `ResponseInputText object { text, type, prompt_cache_breakpoint }` + Specifies the event type. For a click action, this property is always `click`. - A text input to the model. + - `"click"` - - `text: string` + - `x: number` - The text input to the model. + The x-coordinate where the click occurred. - - `type: "input_text"` + - `y: number` - The type of the input item. Always `input_text`. + The y-coordinate where the click occurred. - - `"input_text"` + - `keys: optional array of string` - - `prompt_cache_breakpoint: optional object { mode }` + The keys being held while clicking. - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + - `DoubleClick object { keys, type, x, y }` - - `mode: "explicit"` + A double click action. - The breakpoint mode. Always `explicit`. + - `keys: array of string` - - `"explicit"` + The keys being held while double-clicking. - - `ResponseInputImage object { detail, type, file_id, 2 more }` + - `type: "double_click"` - An image input to the model. Learn about [image inputs](/docs/guides/vision). + Specifies the event type. For a double click action, this property is always set to `double_click`. - - `detail: "low" or "high" or "auto" or "original"` + - `"double_click"` - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + - `x: number` - - `"low"` + The x-coordinate where the double click occurred. - - `"high"` + - `y: number` - - `"auto"` + The y-coordinate where the double click occurred. - - `"original"` + - `Drag object { path, type, keys }` - - `type: "input_image"` + A drag action. - The type of the input item. Always `input_image`. + - `path: array of object { x, y }` - - `"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. - - - `prompt_cache_breakpoint: optional object { mode }` - - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - - `mode: "explicit"` - - The breakpoint mode. Always `explicit`. - - - `"explicit"` - - - `ResponseInputFile object { type, detail, file_data, 4 more }` - - A file input to the model. - - - `type: "input_file"` - - The type of the input item. Always `input_file`. - - - `"input_file"` - - - `detail: optional "auto" or "low" or "high"` - - The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. - - - `"auto"` - - - `"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. - - - `prompt_cache_breakpoint: optional object { mode }` - - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - - `mode: "explicit"` - - The breakpoint mode. Always `explicit`. - - - `"explicit"` - - - `role: "user" or "assistant" or "system" or "developer"` - - The role of the message input. One of `user`, `assistant`, `system`, or - `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 + An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg ``` [ @@ -33091,1454 +31496,3082 @@ the `background` parameter set to `true` can be cancelled. Always `auto`. - - `"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"` + + - `allowed_callers: optional array of "direct" or "programmatic"` + + The tool invocation context(s). + + - `"direct"` + + - `"programmatic"` + + - `ProgrammaticToolCalling object { type }` + + - `type: "programmatic_tool_calling"` + + The type of the tool. Always `programmatic_tool_calling`. + + - `"programmatic_tool_calling"` + + - `ImageGeneration object { type, action, background, 9 more }` + + A tool that generates images using the GPT image models. + + - `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, allowed_callers, environment }` + + A tool that allows the model to execute shell commands. + + - `type: "shell"` + + The type of the shell tool. Always `shell`. + + - `"shell"` + + - `allowed_callers: optional array of "direct" or "programmatic"` + + The tool invocation context(s). + + - `"direct"` + + - `"programmatic"` + + - `environment: optional ContainerAuto or LocalEnvironment or ContainerReference` + + - `ContainerAuto object { type, file_ids, memory_limit, 2 more }` + + - `LocalEnvironment object { type, skills }` + + - `ContainerReference object { container_id, type }` + + - `Custom object { name, type, allowed_callers, 3 more }` + + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) + + - `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"` + + - `allowed_callers: optional array of "direct" or "programmatic"` + + The tool invocation context(s). + + - `"direct"` + + - `"programmatic"` + + - `defer_loading: optional boolean` + + Whether this tool should be deferred and discovered via tool search. + + - `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, allowed_callers, 5 more } or object { name, type, allowed_callers, 3 more }` + + The function/custom tools available inside this namespace. + + - `Function object { name, type, allowed_callers, 5 more }` + + - `name: string` + + - `type: "function"` + + - `"function"` + + - `allowed_callers: optional array of "direct" or "programmatic"` + + The tool invocation context(s). + + - `"direct"` + + - `"programmatic"` + + - `defer_loading: optional boolean` + + Whether this function should be deferred and discovered via tool search. + + - `description: optional string` + + - `output_schema: optional map[unknown]` + + A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. + + - `parameters: optional unknown` + + - `strict: optional boolean` + + Whether to enforce strict parameter validation. If omitted, Responses attempts to use strict validation when the schema is compatible, and falls back to non-strict validation otherwise. + + - `Custom object { name, type, allowed_callers, 3 more }` + + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) + + - `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"` + + - `allowed_callers: optional array of "direct" or "programmatic"` + + The tool invocation context(s). + + - `"direct"` + + - `"programmatic"` + + - `defer_loading: optional boolean` + + Whether this tool should be deferred and discovered via tool search. + + - `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, allowed_callers }` + + 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"` + + - `allowed_callers: optional array of "direct" or "programmatic"` + + The tool invocation context(s). + + - `"direct"` + + - `"programmatic"` + + - `top_p: number` + + An alternative to sampling with temperature, called nucleus sampling, + where the model considers the results of the tokens with top_p probability + mass. So 0.1 means only the tokens comprising the top 10% probability mass + are considered. + + We generally recommend altering this or `temperature` but not both. + + - `background: optional boolean` + + Whether to run the model response in the background. + [Learn more](/docs/guides/background). + + - `completed_at: optional number` + + Unix timestamp (in seconds) of when this Response was completed. + Only present when the status is `completed`. + + - `conversation: optional object { id }` + + The conversation that this response belonged to. Input items and output items from this response were automatically added to this conversation. + + - `id: string` + + The unique ID of the conversation that this response was associated with. + + - `max_output_tokens: optional number` + + An upper bound for the number of tokens that can be generated for a response, including visible output tokens and [reasoning tokens](/docs/guides/reasoning). + + - `max_tool_calls: optional number` + + The maximum number of total calls to built-in tools that can be processed in a response. This maximum number applies across all built-in tool calls, not per individual tool. Any further attempts to call a tool by the model will be ignored. + + - `moderation: optional object { input, output }` + + Moderation results for the response input and output, if moderated completions were requested. + + - `input: object { categories, category_applied_input_types, category_scores, 3 more } or object { code, message, type }` + + Moderation for the response input. + + - `ModerationResult object { categories, category_applied_input_types, category_scores, 3 more }` + + A moderation result produced for the response input or output. + + - `categories: map[boolean]` + + A dictionary of moderation categories to booleans, True if the input is flagged under this category. + + - `category_applied_input_types: map[array of "text" or "image"]` + + Which modalities of input are reflected by the score for each category. + + - `"text"` + + - `"image"` + + - `category_scores: map[number]` + + A dictionary of moderation categories to scores. + + - `flagged: boolean` + + A boolean indicating whether the content was flagged by any category. + + - `model: string` + + The moderation model that produced this result. + + - `type: "moderation_result"` + + The object type, which was always `moderation_result` for successful moderation results. + + - `"moderation_result"` + + - `Error object { code, message, type }` + + An error produced while attempting moderation for the response input or output. + + - `code: string` + + The error code. + + - `message: string` + + The error message. + + - `type: "error"` + + The object type, which was always `error` for moderation failures. + + - `"error"` + + - `output: object { categories, category_applied_input_types, category_scores, 3 more } or object { code, message, type }` + + Moderation for the response output. + + - `ModerationResult object { categories, category_applied_input_types, category_scores, 3 more }` + + A moderation result produced for the response input or output. + + - `categories: map[boolean]` + + A dictionary of moderation categories to booleans, True if the input is flagged under this category. + + - `category_applied_input_types: map[array of "text" or "image"]` + + Which modalities of input are reflected by the score for each category. + + - `"text"` + + - `"image"` + + - `category_scores: map[number]` + + A dictionary of moderation categories to scores. + + - `flagged: boolean` + + A boolean indicating whether the content was flagged by any category. + + - `model: string` + + The moderation model that produced this result. + + - `type: "moderation_result"` + + The object type, which was always `moderation_result` for successful moderation results. + + - `"moderation_result"` + + - `Error object { code, message, type }` + + An error produced while attempting moderation for the response input or output. + + - `code: string` + + The error code. + + - `message: string` + + The error message. + + - `type: "error"` + + The object type, which was always `error` for moderation failures. + + - `"error"` + + - `output_text: optional string` + + SDK-only convenience property that contains the aggregated text output + from all `output_text` items in the `output` array, if any are present. + Supported in the Python and JavaScript SDKs. + + - `previous_response_id: optional string` + + The unique ID of the previous response to the model. Use this to + create multi-turn conversations. Learn more about + [conversation state](/docs/guides/conversation-state). Cannot be used in conjunction with `conversation`. + + - `prompt: optional ResponsePrompt` + + Reference to a prompt template and its variables. + [Learn more](/docs/guides/text?api-mode=responses#reusable-prompts). + + - `id: string` + + The unique identifier of the prompt template to use. + + - `variables: optional map[string or ResponseInputText or ResponseInputImage or ResponseInputFile]` + + Optional map of values to substitute in for variables in your + prompt. The substitution values can either be strings, or other + Response input types like images or files. + + - `string` + + - `ResponseInputText object { text, type, prompt_cache_breakpoint }` + + A text input to the model. + + - `ResponseInputImage object { detail, type, file_id, 2 more }` + + An image input to the model. Learn about [image inputs](/docs/guides/vision). + + - `ResponseInputFile object { type, detail, file_data, 4 more }` + + A file input to the model. + + - `version: optional string` + + Optional version of the prompt template. + + - `prompt_cache_key: optional string` + + Used by OpenAI to cache responses for similar requests to optimize your cache hit rates. Replaces the `user` field. [Learn more](/docs/guides/prompt-caching). + + - `prompt_cache_options: optional object { mode, ttl }` + + The prompt-caching options that were applied to the response. Supported for `gpt-5.6` and later models. + + - `mode: "implicit" or "explicit"` + + Whether implicit prompt-cache breakpoints were enabled. + + - `"implicit"` + + - `"explicit"` + + - `ttl: "30m"` + + The minimum lifetime applied to each cache breakpoint. + + - `"30m"` + + - `prompt_cache_retention: optional "in_memory" or "24h"` + + Deprecated. Use `prompt_cache_options.ttl` instead. + + The retention policy for the prompt cache. Set to `24h` to enable extended prompt caching, which keeps cached prefixes active for longer, up to a maximum of 24 hours. [Learn more](/docs/guides/prompt-caching#prompt-cache-retention). + This field expresses a maximum retention policy, while + `prompt_cache_options.ttl` expresses a minimum cache lifetime. The two + fields are independent and do not interact. + For `gpt-5.5`, `gpt-5.5-pro`, and future models, only `24h` is supported. + + For older models that support both `in_memory` and `24h`, the default depends on your organization's data retention policy: + + - Organizations without ZDR enabled default to `24h`. + - Organizations with ZDR enabled default to `in_memory` when `prompt_cache_retention` is not specified. + + - `"in_memory"` + + - `"24h"` + + - `reasoning: optional Reasoning` + + **gpt-5 and o-series models only** + + Configuration options for + [reasoning models](https://platform.openai.com/docs/guides/reasoning). + + - `context: optional "auto" or "current_turn" or "all_turns"` + + Controls which reasoning items are rendered back to the model on later turns. + If omitted or set to `auto`, the model determines the context mode. The + `gpt-5.6` model family defaults to `all_turns`; earlier models default to + `current_turn`. + + When returned on a response, this is the effective reasoning context mode + used for the response. + + - `"auto"` + + - `"current_turn"` + + - `"all_turns"` + + - `effort: optional ReasoningEffort` + + Constrains effort on reasoning for reasoning models. Currently supported + values are `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max`. + Reducing reasoning effort can result in faster responses and fewer tokens + used on reasoning in a response. Not all reasoning models support every + value. See the + [reasoning guide](https://platform.openai.com/docs/guides/reasoning) + for model-specific support. + + - `"none"` + + - `"minimal"` + + - `"low"` + + - `"medium"` + + - `"high"` + + - `"xhigh"` + + - `"max"` + + - `generate_summary: optional "auto" or "concise" or "detailed"` + + **Deprecated:** use `summary` instead. + + A summary of the reasoning performed by the model. This can be + useful for debugging and understanding the model's reasoning process. + One of `auto`, `concise`, or `detailed`. + + - `"auto"` + + - `"concise"` + + - `"detailed"` + + - `mode: optional string or "standard" or "pro"` + + Controls the reasoning execution mode for the request. + + When returned on a response, this is the effective execution mode. + + - `string` + + - `"standard" or "pro"` + + Controls the reasoning execution mode for the request. + + When returned on a response, this is the effective execution mode. + + - `"standard"` + + - `"pro"` + + - `summary: optional "auto" or "concise" or "detailed"` + + A summary of the reasoning performed by the model. This can be + useful for debugging and understanding the model's reasoning process. + One of `auto`, `concise`, or `detailed`. + + `concise` is supported for `computer-use-preview` models and all reasoning models after `gpt-5`. + + - `"auto"` + + - `"concise"` + + - `"detailed"` + + - `safety_identifier: optional string` + + A stable identifier used to help detect users of your application that may be violating OpenAI's usage policies. + The IDs should be a string that uniquely identifies each user, with a maximum length of 64 characters. We recommend hashing their username or email address, in order to avoid sending us any identifying information. [Learn more](/docs/guides/safety-best-practices#safety-identifiers). + + - `service_tier: optional "auto" or "default" or "flex" or 2 more` + + Specifies the processing type used for serving the request. + + - If set to 'auto', then the request will be processed with the service tier configured in the Project settings. Unless otherwise configured, the Project will use 'default'. + - If set to 'default', then the request will be processed with the standard pricing and performance for the selected model. + - If set to '[flex](/docs/guides/flex-processing)' or '[priority](https://openai.com/api-priority-processing/)', then the request will be processed with the corresponding service tier. + - When not set, the default behavior is 'auto'. + + When the `service_tier` parameter is set, the response body will include the `service_tier` value based on the processing mode actually used to serve the request. This response value may be different from the value set in the parameter. + + - `"auto"` + + - `"default"` + + - `"flex"` + + - `"scale"` + + - `"priority"` + + - `status: optional ResponseStatus` + + The status of the response generation. One of `completed`, `failed`, + `in_progress`, `cancelled`, `queued`, or `incomplete`. + + - `"completed"` + + - `"failed"` + + - `"in_progress"` + + - `"cancelled"` + + - `"queued"` + + - `"incomplete"` + + - `text: optional ResponseTextConfig` + + Configuration options for a text response from the model. Can be plain + text or structured JSON data. Learn more: + + - [Text inputs and outputs](/docs/guides/text) + - [Structured Outputs](/docs/guides/structured-outputs) + + - `format: optional ResponseFormatTextConfig` + + An object specifying the format that the model must output. + + Configuring `{ "type": "json_schema" }` enables Structured Outputs, + which ensures the model will match your supplied JSON schema. Learn more in the + [Structured Outputs guide](/docs/guides/structured-outputs). + + The default format is `{ "type": "text" }` with no additional options. + + **Not recommended for gpt-4o and newer models:** + + Setting to `{ "type": "json_object" }` enables the older JSON mode, which + ensures the message the model generates is valid JSON. Using `json_schema` + is preferred for models that support it. + + - `ResponseFormatText object { type }` + + Default response format. Used to generate text responses. + + - `type: "text"` + + The type of response format being defined. Always `text`. + + - `"text"` + + - `ResponseFormatTextJSONSchemaConfig object { name, schema, type, 2 more }` + + JSON Schema response format. Used to generate structured JSON responses. + Learn more about [Structured Outputs](/docs/guides/structured-outputs). + + - `name: string` + + The name of the response format. Must be a-z, A-Z, 0-9, or contain + underscores and dashes, with a maximum length of 64. + + - `schema: map[unknown]` + + The schema for the response format, described as a JSON Schema object. + Learn how to build JSON schemas [here](https://json-schema.org/). + + - `type: "json_schema"` + + The type of response format being defined. Always `json_schema`. + + - `"json_schema"` + + - `description: optional string` + + A description of what the response format is for, used by the model to + determine how to respond in the format. + + - `strict: optional boolean` + + Whether to enable strict schema adherence when generating the output. + If set to true, the model will always follow the exact schema defined + in the `schema` field. Only a subset of JSON Schema is supported when + `strict` is `true`. To learn more, read the [Structured Outputs + guide](/docs/guides/structured-outputs). + + - `ResponseFormatJSONObject object { type }` + + JSON object response format. An older method of generating JSON responses. + Using `json_schema` is recommended for models that support it. Note that the + model will not generate JSON without a system or user message instructing it + to do so. + + - `type: "json_object"` + + The type of response format being defined. Always `json_object`. + + - `"json_object"` + + - `verbosity: optional "low" or "medium" or "high"` + + Constrains the verbosity of the model's response. Lower values will result in + more concise responses, while higher values will result in more verbose responses. + Currently supported values are `low`, `medium`, and `high`. The default is + `medium`. + + - `"low"` + + - `"medium"` + + - `"high"` + + - `top_logprobs: optional number` + + An integer between 0 and 20 specifying the maximum number of most likely + tokens to return at each token position, each with an associated log + probability. In some cases, the number of returned tokens may be fewer than + requested. + + - `truncation: optional "auto" or "disabled"` + + The truncation strategy to use for the model response. + + - `auto`: If the input to this Response exceeds + the model's context window size, the model will truncate the + response to fit the context window by dropping items from the beginning of the conversation. + - `disabled` (default): If the input size will exceed the context window + size for a model, the request will fail with a 400 error. + + - `"auto"` + + - `"disabled"` + + - `usage: optional ResponseUsage` + + Represents token usage details including input tokens, output tokens, + a breakdown of output tokens, and the total tokens used. + + - `input_tokens: number` + + The number of input tokens. + + - `input_tokens_details: object { cache_write_tokens, cached_tokens }` + + A detailed breakdown of the input tokens. + + - `cache_write_tokens: number` + + The number of input tokens that were written to the cache. + + - `cached_tokens: number` + + The number of tokens that were retrieved from the cache. + [More on prompt caching](/docs/guides/prompt-caching). + + - `output_tokens: number` + + The number of output tokens. + + - `output_tokens_details: object { reasoning_tokens }` + + A detailed breakdown of the output tokens. + + - `reasoning_tokens: number` + + The number of reasoning tokens. + + - `total_tokens: number` + + The total number of tokens used. + + - `user: optional string` + + This field is being replaced by `safety_identifier` and `prompt_cache_key`. Use `prompt_cache_key` instead to maintain caching optimizations. + A stable identifier for your end-users. + Used to boost cache hit rates by better bucketing similar requests and to help OpenAI detect and prevent abuse. [Learn more](/docs/guides/safety-best-practices#safety-identifiers). + +### Example + +```http +curl https://api.openai.com/v1/responses \ + -H 'Content-Type: application/json' \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -d '{ + "model": "gpt-5.1", + "prompt_cache_key": "prompt-cache-key-1234", + "safety_identifier": "safety-identifier-1234", + "temperature": 1, + "top_p": 1, + "user": "user-1234" + }' +``` + +#### Response + +```json +{ + "id": "id", + "created_at": 0, + "error": { + "code": "server_error", + "message": "message" + }, + "incomplete_details": { + "reason": "max_output_tokens" + }, + "instructions": "string", + "metadata": { + "foo": "string" + }, + "model": "gpt-5.1", + "object": "response", + "output": [ + { + "id": "id", + "content": [ + { + "annotations": [ + { + "file_id": "file_id", + "filename": "filename", + "index": 0, + "type": "file_citation" + } + ], + "logprobs": [ + { + "token": "token", + "bytes": [ + 0 + ], + "logprob": 0, + "top_logprobs": [ + { + "token": "token", + "bytes": [ + 0 + ], + "logprob": 0 + } + ] + } + ], + "text": "text", + "type": "output_text" + } + ], + "role": "assistant", + "status": "in_progress", + "type": "message", + "phase": "commentary" + } + ], + "parallel_tool_calls": true, + "temperature": 1, + "tool_choice": "none", + "tools": [ + { + "name": "name", + "parameters": { + "foo": "bar" + }, + "strict": true, + "type": "function", + "allowed_callers": [ + "direct" + ], + "defer_loading": true, + "description": "description", + "output_schema": { + "foo": "bar" + } + } + ], + "top_p": 1, + "background": true, + "completed_at": 0, + "conversation": { + "id": "id" + }, + "max_output_tokens": 0, + "max_tool_calls": 0, + "moderation": { + "input": { + "categories": { + "foo": true + }, + "category_applied_input_types": { + "foo": [ + "text" + ] + }, + "category_scores": { + "foo": 0 + }, + "flagged": true, + "model": "model", + "type": "moderation_result" + }, + "output": { + "categories": { + "foo": true + }, + "category_applied_input_types": { + "foo": [ + "text" + ] + }, + "category_scores": { + "foo": 0 + }, + "flagged": true, + "model": "model", + "type": "moderation_result" + } + }, + "output_text": "output_text", + "previous_response_id": "previous_response_id", + "prompt": { + "id": "id", + "variables": { + "foo": "string" + }, + "version": "version" + }, + "prompt_cache_key": "prompt-cache-key-1234", + "prompt_cache_options": { + "mode": "implicit", + "ttl": "30m" + }, + "prompt_cache_retention": "in_memory", + "reasoning": { + "context": "auto", + "effort": "none", + "generate_summary": "auto", + "mode": "standard", + "summary": "auto" + }, + "safety_identifier": "safety-identifier-1234", + "service_tier": "auto", + "status": "completed", + "text": { + "format": { + "type": "text" + }, + "verbosity": "low" + }, + "top_logprobs": 0, + "truncation": "auto", + "usage": { + "input_tokens": 0, + "input_tokens_details": { + "cache_write_tokens": 0, + "cached_tokens": 0 + }, + "output_tokens": 0, + "output_tokens_details": { + "reasoning_tokens": 0 + }, + "total_tokens": 0 + }, + "user": "user-1234" +} +``` + +### File input + +```http +curl https://api.openai.com/v1/responses \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -d '{ + "model": "gpt-5.4", + "input": [ + { + "role": "user", + "content": [ + {"type": "input_text", "text": "what is in this file?"}, + { + "type": "input_file", + "file_url": "https://www.berkshirehathaway.com/letters/2024ltr.pdf", + "detail": "auto" + } + ] + } + ] + }' +``` + +#### Response + +```json +{ + "id": "resp_686eef60237881a2bd1180bb8b13de430e34c516d176ff86", + "object": "response", + "created_at": 1752100704, + "status": "completed", + "completed_at": 1752100705, + "background": false, + "error": null, + "incomplete_details": null, + "instructions": null, + "max_output_tokens": null, + "max_tool_calls": null, + "model": "gpt-5.4", + "output": [ + { + "id": "msg_686eef60d3e081a29283bdcbc4322fd90e34c516d176ff86", + "type": "message", + "status": "completed", + "content": [ + { + "type": "output_text", + "annotations": [], + "logprobs": [], + "text": "The file seems to contain excerpts from a letter to the shareholders of Berkshire Hathaway Inc., likely written by Warren Buffett. It covers several topics:\n\n1. **Communication Philosophy**: Buffett emphasizes the importance of transparency and candidness in reporting mistakes and successes to shareholders.\n\n2. **Mistakes and Learnings**: The letter acknowledges past mistakes in business assessments and management hires, highlighting the importance of correcting errors promptly.\n\n3. **CEO Succession**: Mention of Greg Abel stepping in as the new CEO and continuing the tradition of honest communication.\n\n4. **Pete Liegl Story**: A detailed account of acquiring Forest River and the relationship with its founder, highlighting trust and effective business decisions.\n\n5. **2024 Performance**: Overview of business performance, particularly in insurance and investment activities, with a focus on GEICO's improvement.\n\n6. **Tax Contributions**: Discussion of significant tax payments to the U.S. Treasury, credited to shareholders' reinvestments.\n\n7. **Investment Strategy**: A breakdown of Berkshire\u2019s investments in both controlled subsidiaries and marketable equities, along with a focus on long-term holding strategies.\n\n8. **American Capitalism**: Reflections on America\u2019s economic development and Berkshire\u2019s role within it.\n\n9. **Property-Casualty Insurance**: Insights into the P/C insurance business model and its challenges and benefits.\n\n10. **Japanese Investments**: Information about Berkshire\u2019s investments in Japanese companies and future plans.\n\n11. **Annual Meeting**: Details about the upcoming annual gathering in Omaha, including schedule changes and new book releases.\n\n12. **Personal Anecdotes**: Light-hearted stories about family and interactions, conveying Buffett's personable approach.\n\n13. **Financial Performance Data**: Tables comparing Berkshire\u2019s annual performance to the S&P 500, showing impressive long-term gains.\n\nOverall, the letter reinforces Berkshire Hathaway's commitment to transparency, investment in both its businesses and the wider economy, and emphasizes strong leadership and prudent financial management." + } + ], + "role": "assistant" + } + ], + "parallel_tool_calls": true, + "previous_response_id": null, + "reasoning": { + "effort": null, + "summary": null + }, + "service_tier": "default", + "store": true, + "temperature": 1.0, + "text": { + "format": { + "type": "text" + } + }, + "tool_choice": "auto", + "tools": [], + "top_logprobs": 0, + "top_p": 1.0, + "truncation": "disabled", + "usage": { + "input_tokens": 8438, + "input_tokens_details": { + "cached_tokens": 0, + "cache_write_tokens": 0 + }, + "output_tokens": 398, + "output_tokens_details": { + "reasoning_tokens": 0 + }, + "total_tokens": 8836 + }, + "user": null, + "metadata": {} +} +``` + +### File search + +```http +curl https://api.openai.com/v1/responses \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -d '{ + "model": "gpt-5.4", + "tools": [{ + "type": "file_search", + "vector_store_ids": ["vs_1234567890"], + "max_num_results": 20 + }], + "input": "What are the attributes of an ancient brown dragon?" + }' +``` + +#### Response + +```json +{ + "id": "resp_67ccf4c55fc48190b71bd0463ad3306d09504fb6872380d7", + "object": "response", + "created_at": 1741485253, + "status": "completed", + "completed_at": 1741485254, + "error": null, + "incomplete_details": null, + "instructions": null, + "max_output_tokens": null, + "model": "gpt-5.4", + "output": [ + { + "type": "file_search_call", + "id": "fs_67ccf4c63cd08190887ef6464ba5681609504fb6872380d7", + "status": "completed", + "queries": [ + "attributes of an ancient brown dragon" + ], + "results": null + }, + { + "type": "message", + "id": "msg_67ccf4c93e5c81909d595b369351a9d309504fb6872380d7", + "status": "completed", + "role": "assistant", + "content": [ + { + "type": "output_text", + "text": "The attributes of an ancient brown dragon include...", + "annotations": [ + { + "type": "file_citation", + "index": 320, + "file_id": "file-4wDz5b167pAf72nx1h9eiN", + "filename": "dragons.pdf" + }, + { + "type": "file_citation", + "index": 576, + "file_id": "file-4wDz5b167pAf72nx1h9eiN", + "filename": "dragons.pdf" + }, + { + "type": "file_citation", + "index": 815, + "file_id": "file-4wDz5b167pAf72nx1h9eiN", + "filename": "dragons.pdf" + }, + { + "type": "file_citation", + "index": 815, + "file_id": "file-4wDz5b167pAf72nx1h9eiN", + "filename": "dragons.pdf" + }, + { + "type": "file_citation", + "index": 1030, + "file_id": "file-4wDz5b167pAf72nx1h9eiN", + "filename": "dragons.pdf" + }, + { + "type": "file_citation", + "index": 1030, + "file_id": "file-4wDz5b167pAf72nx1h9eiN", + "filename": "dragons.pdf" + }, + { + "type": "file_citation", + "index": 1156, + "file_id": "file-4wDz5b167pAf72nx1h9eiN", + "filename": "dragons.pdf" + }, + { + "type": "file_citation", + "index": 1225, + "file_id": "file-4wDz5b167pAf72nx1h9eiN", + "filename": "dragons.pdf" + } + ] + } + ] + } + ], + "parallel_tool_calls": true, + "previous_response_id": null, + "reasoning": { + "effort": null, + "summary": null + }, + "store": true, + "temperature": 1.0, + "text": { + "format": { + "type": "text" + } + }, + "tool_choice": "auto", + "tools": [ + { + "type": "file_search", + "filters": null, + "max_num_results": 20, + "ranking_options": { + "ranker": "auto", + "score_threshold": 0.0 + }, + "vector_store_ids": [ + "vs_1234567890" + ] + } + ], + "top_p": 1.0, + "truncation": "disabled", + "usage": { + "input_tokens": 18307, + "input_tokens_details": { + "cached_tokens": 0, + "cache_write_tokens": 0 + }, + "output_tokens": 348, + "output_tokens_details": { + "reasoning_tokens": 0 + }, + "total_tokens": 18655 + }, + "user": null, + "metadata": {} +} +``` + +### Functions + +```http +curl https://api.openai.com/v1/responses \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -d '{ + "model": "gpt-5.4", + "input": "What is the weather like in Boston today?", + "tools": [ + { + "type": "function", + "name": "get_current_weather", + "description": "Get the current weather in a given location", + "parameters": { + "type": "object", + "properties": { + "location": { + "type": "string", + "description": "The city and state, e.g. San Francisco, CA" + }, + "unit": { + "type": "string", + "enum": ["celsius", "fahrenheit"] + } + }, + "required": ["location", "unit"] + } + } + ], + "tool_choice": "auto" + }' +``` + +#### Response + +```json +{ + "id": "resp_67ca09c5efe0819096d0511c92b8c890096610f474011cc0", + "object": "response", + "created_at": 1741294021, + "status": "completed", + "completed_at": 1741294022, + "error": null, + "incomplete_details": null, + "instructions": null, + "max_output_tokens": null, + "model": "gpt-5.4", + "output": [ + { + "type": "function_call", + "id": "fc_67ca09c6bedc8190a7abfec07b1a1332096610f474011cc0", + "call_id": "call_unLAR8MvFNptuiZK6K6HCy5k", + "name": "get_current_weather", + "arguments": "{\"location\":\"Boston, MA\",\"unit\":\"celsius\"}", + "status": "completed" + } + ], + "parallel_tool_calls": true, + "previous_response_id": null, + "reasoning": { + "effort": null, + "summary": null + }, + "store": true, + "temperature": 1.0, + "text": { + "format": { + "type": "text" + } + }, + "tool_choice": "auto", + "tools": [ + { + "type": "function", + "description": "Get the current weather in a given location", + "name": "get_current_weather", + "parameters": { + "type": "object", + "properties": { + "location": { + "type": "string", + "description": "The city and state, e.g. San Francisco, CA" + }, + "unit": { + "type": "string", + "enum": [ + "celsius", + "fahrenheit" + ] + } + }, + "required": [ + "location", + "unit" + ] + }, + "strict": true + } + ], + "top_p": 1.0, + "truncation": "disabled", + "usage": { + "input_tokens": 291, + "output_tokens": 23, + "output_tokens_details": { + "reasoning_tokens": 0 + }, + "total_tokens": 314 + }, + "user": null, + "metadata": {} +} +``` + +### Image input + +```http +curl https://api.openai.com/v1/responses \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -d '{ + "model": "gpt-5.4", + "input": [ + { + "role": "user", + "content": [ + {"type": "input_text", "text": "what is in this image?"}, + { + "type": "input_image", + "image_url": "https://upload.wikimedia.org/wikipedia/commons/thumb/d/dd/Gfp-wisconsin-madison-the-nature-boardwalk.jpg/2560px-Gfp-wisconsin-madison-the-nature-boardwalk.jpg" + } + ] + } + ] + }' +``` + +#### Response + +```json +{ + "id": "resp_67ccd3a9da748190baa7f1570fe91ac604becb25c45c1d41", + "object": "response", + "created_at": 1741476777, + "status": "completed", + "completed_at": 1741476778, + "error": null, + "incomplete_details": null, + "instructions": null, + "max_output_tokens": null, + "model": "gpt-5.4", + "output": [ + { + "type": "message", + "id": "msg_67ccd3acc8d48190a77525dc6de64b4104becb25c45c1d41", + "status": "completed", + "role": "assistant", + "content": [ + { + "type": "output_text", + "text": "The image depicts a scenic landscape with a wooden boardwalk or pathway leading through lush, green grass under a blue sky with some clouds. The setting suggests a peaceful natural area, possibly a park or nature reserve. There are trees and shrubs in the background.", + "annotations": [] + } + ] + } + ], + "parallel_tool_calls": true, + "previous_response_id": null, + "reasoning": { + "effort": null, + "summary": null + }, + "store": true, + "temperature": 1.0, + "text": { + "format": { + "type": "text" + } + }, + "tool_choice": "auto", + "tools": [], + "top_p": 1.0, + "truncation": "disabled", + "usage": { + "input_tokens": 328, + "input_tokens_details": { + "cached_tokens": 0, + "cache_write_tokens": 0 + }, + "output_tokens": 52, + "output_tokens_details": { + "reasoning_tokens": 0 + }, + "total_tokens": 380 + }, + "user": null, + "metadata": {} +} +``` + +### Reasoning - - `file_ids: optional array of string` +```http +curl https://api.openai.com/v1/responses \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -d '{ + "model": "o3-mini", + "input": "How much wood would a woodchuck chuck?", + "reasoning": { + "effort": "high" + } + }' +``` - An optional list of uploaded files to make available to your code. +#### Response - - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` +```json +{ + "id": "resp_67ccd7eca01881908ff0b5146584e408072912b2993db808", + "object": "response", + "created_at": 1741477868, + "status": "completed", + "completed_at": 1741477869, + "error": null, + "incomplete_details": null, + "instructions": null, + "max_output_tokens": null, + "model": "o1-2024-12-17", + "output": [ + { + "type": "message", + "id": "msg_67ccd7f7b5848190a6f3e95d809f6b44072912b2993db808", + "status": "completed", + "role": "assistant", + "content": [ + { + "type": "output_text", + "text": "The classic tongue twister...", + "annotations": [] + } + ] + } + ], + "parallel_tool_calls": true, + "previous_response_id": null, + "reasoning": { + "effort": "high", + "summary": null + }, + "store": true, + "temperature": 1.0, + "text": { + "format": { + "type": "text" + } + }, + "tool_choice": "auto", + "tools": [], + "top_p": 1.0, + "truncation": "disabled", + "usage": { + "input_tokens": 81, + "input_tokens_details": { + "cached_tokens": 0, + "cache_write_tokens": 0 + }, + "output_tokens": 1035, + "output_tokens_details": { + "reasoning_tokens": 832 + }, + "total_tokens": 1116 + }, + "user": null, + "metadata": {} +} +``` - The memory limit for the code interpreter container. +### Streaming - - `"1g"` +```http +curl https://api.openai.com/v1/responses \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -d '{ + "model": "gpt-5.4", + "instructions": "You are a helpful assistant.", + "input": "Hello!", + "stream": true + }' +``` - - `"4g"` +#### Response - - `"16g"` +```json +event: response.created +data: {"type":"response.created","response":{"id":"resp_67c9fdcecf488190bdd9a0409de3a1ec07b8b0ad4e5eb654","object":"response","created_at":1741290958,"status":"in_progress","error":null,"incomplete_details":null,"instructions":"You are a helpful assistant.","max_output_tokens":null,"model":"gpt-5.4","output":[],"parallel_tool_calls":true,"previous_response_id":null,"reasoning":{"effort":null,"summary":null},"store":true,"temperature":1.0,"text":{"format":{"type":"text"}},"tool_choice":"auto","tools":[],"top_p":1.0,"truncation":"disabled","usage":null,"user":null,"metadata":{}}} - - `"64g"` +event: response.in_progress +data: {"type":"response.in_progress","response":{"id":"resp_67c9fdcecf488190bdd9a0409de3a1ec07b8b0ad4e5eb654","object":"response","created_at":1741290958,"status":"in_progress","error":null,"incomplete_details":null,"instructions":"You are a helpful assistant.","max_output_tokens":null,"model":"gpt-5.4","output":[],"parallel_tool_calls":true,"previous_response_id":null,"reasoning":{"effort":null,"summary":null},"store":true,"temperature":1.0,"text":{"format":{"type":"text"}},"tool_choice":"auto","tools":[],"top_p":1.0,"truncation":"disabled","usage":null,"user":null,"metadata":{}}} - - `network_policy: optional ContainerNetworkPolicyDisabled or ContainerNetworkPolicyAllowlist` +event: response.output_item.added +data: {"type":"response.output_item.added","output_index":0,"item":{"id":"msg_67c9fdcf37fc8190ba82116e33fb28c507b8b0ad4e5eb654","type":"message","status":"in_progress","role":"assistant","content":[]}} - Network access policy for the container. +event: response.content_part.added +data: {"type":"response.content_part.added","item_id":"msg_67c9fdcf37fc8190ba82116e33fb28c507b8b0ad4e5eb654","output_index":0,"content_index":0,"part":{"type":"output_text","text":"","annotations":[]}} - - `ContainerNetworkPolicyDisabled object { type }` +event: response.output_text.delta +data: {"type":"response.output_text.delta","item_id":"msg_67c9fdcf37fc8190ba82116e33fb28c507b8b0ad4e5eb654","output_index":0,"content_index":0,"delta":"Hi"} - - `ContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` +... - - `type: "code_interpreter"` +event: response.output_text.done +data: {"type":"response.output_text.done","item_id":"msg_67c9fdcf37fc8190ba82116e33fb28c507b8b0ad4e5eb654","output_index":0,"content_index":0,"text":"Hi there! How can I assist you today?"} - The type of the code interpreter tool. Always `code_interpreter`. +event: response.content_part.done +data: {"type":"response.content_part.done","item_id":"msg_67c9fdcf37fc8190ba82116e33fb28c507b8b0ad4e5eb654","output_index":0,"content_index":0,"part":{"type":"output_text","text":"Hi there! How can I assist you today?","annotations":[]}} - - `"code_interpreter"` +event: response.output_item.done +data: {"type":"response.output_item.done","output_index":0,"item":{"id":"msg_67c9fdcf37fc8190ba82116e33fb28c507b8b0ad4e5eb654","type":"message","status":"completed","role":"assistant","content":[{"type":"output_text","text":"Hi there! How can I assist you today?","annotations":[]}]}} - - `allowed_callers: optional array of "direct" or "programmatic"` +event: response.completed +data: {"type":"response.completed","response":{"id":"resp_67c9fdcecf488190bdd9a0409de3a1ec07b8b0ad4e5eb654","object":"response","created_at":1741290958,"status":"completed","error":null,"incomplete_details":null,"instructions":"You are a helpful assistant.","max_output_tokens":null,"model":"gpt-5.4","output":[{"id":"msg_67c9fdcf37fc8190ba82116e33fb28c507b8b0ad4e5eb654","type":"message","status":"completed","role":"assistant","content":[{"type":"output_text","text":"Hi there! How can I assist you today?","annotations":[]}]}],"parallel_tool_calls":true,"previous_response_id":null,"reasoning":{"effort":null,"summary":null},"store":true,"temperature":1.0,"text":{"format":{"type":"text"}},"tool_choice":"auto","tools":[],"top_p":1.0,"truncation":"disabled","usage":{"input_tokens":37,"output_tokens":11,"output_tokens_details":{"reasoning_tokens":0},"total_tokens":48},"user":null,"metadata":{}}} +``` - The tool invocation context(s). +### Text input - - `"direct"` +```http +curl https://api.openai.com/v1/responses \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -d '{ + "model": "gpt-5.4", + "input": "Tell me a three sentence bedtime story about a unicorn." + }' +``` - - `"programmatic"` +#### Response - - `ProgrammaticToolCalling object { type }` +```json +{ + "id": "resp_67ccd2bed1ec8190b14f964abc0542670bb6a6b452d3795b", + "object": "response", + "created_at": 1741476542, + "status": "completed", + "completed_at": 1741476543, + "error": null, + "incomplete_details": null, + "instructions": null, + "max_output_tokens": null, + "model": "gpt-5.4", + "output": [ + { + "type": "message", + "id": "msg_67ccd2bf17f0819081ff3bb2cf6508e60bb6a6b452d3795b", + "status": "completed", + "role": "assistant", + "content": [ + { + "type": "output_text", + "text": "In a peaceful grove beneath a silver moon, a unicorn named Lumina discovered a hidden pool that reflected the stars. As she dipped her horn into the water, the pool began to shimmer, revealing a pathway to a magical realm of endless night skies. Filled with wonder, Lumina whispered a wish for all who dream to find their own hidden magic, and as she glanced back, her hoofprints sparkled like stardust.", + "annotations": [] + } + ] + } + ], + "parallel_tool_calls": true, + "previous_response_id": null, + "reasoning": { + "effort": null, + "summary": null + }, + "store": true, + "temperature": 1.0, + "text": { + "format": { + "type": "text" + } + }, + "tool_choice": "auto", + "tools": [], + "top_p": 1.0, + "truncation": "disabled", + "usage": { + "input_tokens": 36, + "input_tokens_details": { + "cached_tokens": 0, + "cache_write_tokens": 0 + }, + "output_tokens": 87, + "output_tokens_details": { + "reasoning_tokens": 0 + }, + "total_tokens": 123 + }, + "user": null, + "metadata": {} +} +``` - - `type: "programmatic_tool_calling"` +### Web search - The type of the tool. Always `programmatic_tool_calling`. +```http +curl https://api.openai.com/v1/responses \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -d '{ + "model": "gpt-5.4", + "tools": [{ "type": "web_search_preview" }], + "input": "What was a positive news story from today?" + }' +``` - - `"programmatic_tool_calling"` +#### Response - - `ImageGeneration object { type, action, background, 9 more }` +```json +{ + "id": "resp_67ccf18ef5fc8190b16dbee19bc54e5f087bb177ab789d5c", + "object": "response", + "created_at": 1741484430, + "status": "completed", + "completed_at": 1741484431, + "error": null, + "incomplete_details": null, + "instructions": null, + "max_output_tokens": null, + "model": "gpt-5.4", + "output": [ + { + "type": "web_search_call", + "id": "ws_67ccf18f64008190a39b619f4c8455ef087bb177ab789d5c", + "status": "completed" + }, + { + "type": "message", + "id": "msg_67ccf190ca3881909d433c50b1f6357e087bb177ab789d5c", + "status": "completed", + "role": "assistant", + "content": [ + { + "type": "output_text", + "text": "As of today, March 9, 2025, one notable positive news story...", + "annotations": [ + { + "type": "url_citation", + "start_index": 442, + "end_index": 557, + "url": "https://.../?utm_source=chatgpt.com", + "title": "..." + }, + { + "type": "url_citation", + "start_index": 962, + "end_index": 1077, + "url": "https://.../?utm_source=chatgpt.com", + "title": "..." + }, + { + "type": "url_citation", + "start_index": 1336, + "end_index": 1451, + "url": "https://.../?utm_source=chatgpt.com", + "title": "..." + } + ] + } + ] + } + ], + "parallel_tool_calls": true, + "previous_response_id": null, + "reasoning": { + "effort": null, + "summary": null + }, + "store": true, + "temperature": 1.0, + "text": { + "format": { + "type": "text" + } + }, + "tool_choice": "auto", + "tools": [ + { + "type": "web_search_preview", + "domains": [], + "search_context_size": "medium", + "user_location": { + "type": "approximate", + "city": null, + "country": "US", + "region": null, + "timezone": null + } + } + ], + "top_p": 1.0, + "truncation": "disabled", + "usage": { + "input_tokens": 328, + "input_tokens_details": { + "cached_tokens": 0, + "cache_write_tokens": 0 + }, + "output_tokens": 356, + "output_tokens_details": { + "reasoning_tokens": 0 + }, + "total_tokens": 684 + }, + "user": null, + "metadata": {} +} +``` - A tool that generates images using the GPT image models. +## Delete a model response - - `type: "image_generation"` +**delete** `/responses/{response_id}` - The type of the image generation tool. Always `image_generation`. +Deletes a model response with the given ID. - - `"image_generation"` +### Path Parameters - - `action: optional "generate" or "edit" or "auto"` +- `response_id: string` - Whether to generate a new image or edit an existing image. Default: `auto`. +### Example - - `"generate"` +```http +curl https://api.openai.com/v1/responses/$RESPONSE_ID \ + -X DELETE \ + -H "Authorization: Bearer $OPENAI_API_KEY" +``` - - `"edit"` +### Example - - `"auto"` +```http +curl -X DELETE https://api.openai.com/v1/responses/resp_123 \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $OPENAI_API_KEY" +``` - - `background: optional "transparent" or "opaque" or "auto"` +#### Response - Background type for the generated image. One of `transparent`, - `opaque`, or `auto`. Default: `auto`. +```json +{ + "id": "resp_6786a1bec27481909a17d673315b29f6", + "object": "response", + "deleted": true +} +``` - - `"transparent"` +## Get a model response - - `"opaque"` +**get** `/responses/{response_id}` - - `"auto"` +Retrieves a model response with the given ID. - - `input_fidelity: optional "high" or "low"` +### Path Parameters - 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`. +- `response_id: string` - - `"high"` +### Query Parameters - - `"low"` +- `include: optional array of ResponseIncludable` - - `input_image_mask: optional object { file_id, image_url }` + Additional fields to include in the response. See the `include` + parameter for Response creation above for more information. - Optional mask for inpainting. Contains `image_url` - (string, optional) and `file_id` (string, optional). + - `"file_search_call.results"` - - `file_id: optional string` + - `"web_search_call.results"` - File ID for the mask image. + - `"web_search_call.action.sources"` - - `image_url: optional string` + - `"message.input_image.image_url"` - Base64-encoded mask image. + - `"computer_call_output.output.image_url"` - - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` + - `"code_interpreter_call.outputs"` - The image generation model to use. Default: `gpt-image-1`. + - `"reasoning.encrypted_content"` - - `string` + - `"message.output_text.logprobs"` - - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` +- `include_obfuscation: optional boolean` - The image generation model to use. Default: `gpt-image-1`. + When true, stream obfuscation will be enabled. Stream obfuscation adds + random characters to an `obfuscation` field on streaming delta events + to normalize payload sizes as a mitigation to certain side-channel + attacks. These obfuscation fields are included by default, but add a + small amount of overhead to the data stream. You can set + `include_obfuscation` to false to optimize for bandwidth if you trust + the network links between your application and the OpenAI API. - - `"gpt-image-1"` +- `starting_after: optional number` - - `"gpt-image-1-mini"` + The sequence number of the event after which to start streaming. - - `"gpt-image-1.5"` +- `stream: optional false` - - `moderation: optional "auto" or "low"` + If set to true, the model response data will be streamed to the client + as it is generated using [server-sent events](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events/Using_server-sent_events#Event_stream_format). + See the [Streaming section below](/docs/api-reference/responses-streaming) + for more information. - Moderation level for the generated image. Default: `auto`. + - `false` - - `"auto"` +### Returns - - `"low"` +- `Response object { id, created_at, error, 32 more }` - - `output_compression: optional number` + - `id: string` - Compression level for the output image. Default: 100. + Unique identifier for this Response. - - `output_format: optional "png" or "webp" or "jpeg"` + - `created_at: number` - The output format of the generated image. One of `png`, `webp`, or - `jpeg`. Default: `png`. + Unix timestamp (in seconds) of when this Response was created. - - `"png"` + - `error: ResponseError` - - `"webp"` + An error object returned when the model fails to generate a Response. - - `"jpeg"` + - `code: "server_error" or "rate_limit_exceeded" or "invalid_prompt" or 17 more` - - `partial_images: optional number` + The error code for the response. - Number of partial images to generate in streaming mode, from 0 (default value) to 3. + - `"server_error"` - - `quality: optional "low" or "medium" or "high" or "auto"` + - `"rate_limit_exceeded"` - The quality of the generated image. One of `low`, `medium`, `high`, - or `auto`. Default: `auto`. + - `"invalid_prompt"` - - `"low"` + - `"data_residency_mismatch"` - - `"medium"` + - `"bio_policy"` - - `"high"` + - `"vector_store_timeout"` - - `"auto"` + - `"invalid_image"` - - `size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or "auto"` + - `"invalid_image_format"` - 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`. + - `"invalid_base64_image"` - - `string` + - `"invalid_image_url"` - - `"1024x1024" or "1024x1536" or "1536x1024" or "auto"` + - `"image_too_large"` - 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_too_small"` - - `"1024x1024"` + - `"image_parse_error"` - - `"1024x1536"` + - `"image_content_policy_violation"` - - `"1536x1024"` + - `"invalid_image_mode"` - - `"auto"` + - `"image_file_too_large"` - - `LocalShell object { type }` + - `"unsupported_image_media_type"` - A tool that allows the model to execute shell commands in a local environment. + - `"empty_image_file"` - - `type: "local_shell"` + - `"failed_to_download_image"` - The type of the local shell tool. Always `local_shell`. + - `"image_file_not_found"` - - `"local_shell"` + - `message: string` - - `Shell object { type, allowed_callers, environment }` + A human-readable description of the error. - A tool that allows the model to execute shell commands. + - `incomplete_details: object { reason }` - - `type: "shell"` + Details about why the response is incomplete. - The type of the shell tool. Always `shell`. + - `reason: optional "max_output_tokens" or "content_filter"` - - `"shell"` + The reason why the response is incomplete. - - `allowed_callers: optional array of "direct" or "programmatic"` + - `"max_output_tokens"` - The tool invocation context(s). + - `"content_filter"` - - `"direct"` + - `instructions: string or array of EasyInputMessage or object { content, role, status, type } or ResponseOutputMessage or 29 more` - - `"programmatic"` + A system (or developer) message inserted into the model's context. - - `environment: optional ContainerAuto or LocalEnvironment or ContainerReference` + When using along with `previous_response_id`, the instructions from a previous + response will not be carried over to the next response. This makes it simple + to swap out system (or developer) messages in new responses. - - `ContainerAuto object { type, file_ids, memory_limit, 2 more }` + - `string` - - `LocalEnvironment object { type, skills }` + A text input to the model, equivalent to a text input with the + `developer` role. - - `ContainerReference object { container_id, type }` + - `InputItemList = array of EasyInputMessage or object { content, role, status, type } or ResponseOutputMessage or 29 more` - - `Custom object { name, type, allowed_callers, 3 more }` + A list of one or many input items to the model, containing + different content types. - A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) + - `EasyInputMessage object { content, role, phase, type }` - - `name: string` + 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. - The name of the custom tool, used to identify it in tool calls. + - `content: string or ResponseInputMessageContentList` - - `type: "custom"` + Text, image, or audio input to the model, used to generate a response. + Can also contain previous assistant responses. - The type of the custom tool. Always `custom`. + - `TextInput = string` - - `"custom"` + A text input to the model. - - `allowed_callers: optional array of "direct" or "programmatic"` + - `ResponseInputMessageContentList = array of ResponseInputContent` - The tool invocation context(s). + A list of one or many input items to the model, containing different content + types. - - `"direct"` + - `ResponseInputText object { text, type, prompt_cache_breakpoint }` - - `"programmatic"` + A text input to the model. - - `defer_loading: optional boolean` + - `text: string` - Whether this tool should be deferred and discovered via tool search. + The text input to the model. - - `description: optional string` + - `type: "input_text"` - Optional description of the custom tool, used to provide more context. + The type of the input item. Always `input_text`. - - `format: optional CustomToolInputFormat` + - `"input_text"` - The input format for the custom tool. Default is unconstrained text. + - `prompt_cache_breakpoint: optional object { mode }` - - `Namespace object { description, name, tools, type }` + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - Groups function/custom tools under a shared namespace. + - `mode: "explicit"` - - `description: string` + The breakpoint mode. Always `explicit`. - A description of the namespace shown to the model. + - `"explicit"` - - `name: string` + - `ResponseInputImage object { detail, type, file_id, 2 more }` - The namespace name used in tool calls (for example, `crm`). + An image input to the model. Learn about [image inputs](/docs/guides/vision). - - `tools: array of object { name, type, allowed_callers, 5 more } or object { name, type, allowed_callers, 3 more }` + - `detail: "low" or "high" or "auto" or "original"` - The function/custom tools available inside this namespace. + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - - `Function object { name, type, allowed_callers, 5 more }` + - `"low"` - - `name: string` + - `"high"` - - `type: "function"` + - `"auto"` - - `"function"` + - `"original"` - - `allowed_callers: optional array of "direct" or "programmatic"` + - `type: "input_image"` - The tool invocation context(s). + The type of the input item. Always `input_image`. - - `"direct"` + - `"input_image"` - - `"programmatic"` + - `file_id: optional string` - - `defer_loading: optional boolean` + The ID of the file to be sent to the model. - Whether this function should be deferred and discovered via 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. - - `output_schema: optional map[unknown]` + - `prompt_cache_breakpoint: optional object { mode }` - A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - `parameters: optional unknown` + - `mode: "explicit"` - - `strict: optional boolean` + The breakpoint mode. Always `explicit`. - Whether to enforce strict parameter validation. If omitted, Responses attempts to use strict validation when the schema is compatible, and falls back to non-strict validation otherwise. + - `"explicit"` - - `Custom object { name, type, allowed_callers, 3 more }` + - `ResponseInputFile object { type, detail, file_data, 4 more }` - A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) + A file input to the model. - - `name: string` + - `type: "input_file"` - The name of the custom tool, used to identify it in tool calls. + The type of the input item. Always `input_file`. - - `type: "custom"` + - `"input_file"` - The type of the custom tool. Always `custom`. + - `detail: optional "auto" or "low" or "high"` - - `"custom"` + The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. - - `allowed_callers: optional array of "direct" or "programmatic"` + - `"auto"` - The tool invocation context(s). + - `"low"` - - `"direct"` + - `"high"` - - `"programmatic"` + - `file_data: optional string` - - `defer_loading: optional boolean` + The content of the file to be sent to the model. - Whether this tool should be deferred and discovered via tool search. + - `file_id: optional string` - - `description: optional string` + The ID of the file to be sent to the model. - Optional description of the custom tool, used to provide more context. + - `file_url: optional string` - - `format: optional CustomToolInputFormat` + The URL of the file to be sent to the model. - The input format for the custom tool. Default is unconstrained text. + - `filename: optional string` - - `type: "namespace"` + The name of the file to be sent to the model. - The type of the tool. Always `namespace`. + - `prompt_cache_breakpoint: optional object { mode }` - - `"namespace"` + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - `ToolSearch object { type, description, execution, parameters }` + - `mode: "explicit"` - Hosted or BYOT tool search configuration for deferred tools. + The breakpoint mode. Always `explicit`. - - `type: "tool_search"` + - `"explicit"` - The type of the tool. Always `tool_search`. + - `role: "user" or "assistant" or "system" or "developer"` - - `"tool_search"` + The role of the message input. One of `user`, `assistant`, `system`, or + `developer`. - - `description: optional string` + - `"user"` - Description shown to the model for a client-executed tool search tool. + - `"assistant"` - - `execution: optional "server" or "client"` + - `"system"` - Whether tool search is executed by the server or by the client. + - `"developer"` - - `"server"` + - `phase: optional "commentary" or "final_answer"` - - `"client"` + 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. - - `parameters: optional unknown` + - `"commentary"` - Parameter schema for a client-executed tool search tool. + - `"final_answer"` - - `WebSearchPreview object { type, search_content_types, search_context_size, user_location }` + - `type: optional "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 type of the message input. Always `message`. - - `type: "web_search_preview" or "web_search_preview_2025_03_11"` + - `"message"` - The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. + - `Message object { content, role, status, type }` - - `"web_search_preview"` + 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. - - `"web_search_preview_2025_03_11"` + - `content: ResponseInputMessageContentList` - - `search_content_types: optional array of "text" or "image"` + A list of one or many input items to the model, containing different content + types. - - `"text"` + - `role: "user" or "system" or "developer"` - - `"image"` + The role of the message input. One of `user`, `system`, or `developer`. - - `search_context_size: optional "low" or "medium" or "high"` + - `"user"` - 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. + - `"system"` - - `"low"` + - `"developer"` - - `"medium"` + - `status: optional "in_progress" or "completed" or "incomplete"` - - `"high"` + The status of item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `user_location: optional object { type, city, country, 2 more }` + - `"in_progress"` - The user's location. + - `"completed"` - - `type: "approximate"` + - `"incomplete"` - The type of location approximation. Always `approximate`. + - `type: optional "message"` - - `"approximate"` + The type of the message input. Always set to `message`. - - `city: optional string` + - `"message"` - Free text input for the city of the user, e.g. `San Francisco`. + - `ResponseOutputMessage object { id, content, role, 3 more }` - - `country: optional string` + An output message from the model. - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + - `id: string` - - `region: optional string` + The unique ID of the output message. - Free text input for the region of the user, e.g. `California`. + - `content: array of ResponseOutputText or ResponseOutputRefusal` - - `timezone: optional string` + The content of the output message. - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + - `ResponseOutputText object { annotations, logprobs, text, type }` - - `ApplyPatch object { type, allowed_callers }` + A text output from the model. - Allows the assistant to create, delete, or update files using unified diffs. + - `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: "apply_patch"` + The annotations of the text output. - The type of the tool. Always `apply_patch`. + - `FileCitation object { file_id, filename, index, type }` - - `"apply_patch"` + A citation to a file. - - `allowed_callers: optional array of "direct" or "programmatic"` + - `file_id: string` - The tool invocation context(s). + The ID of the file. - - `"direct"` + - `filename: string` - - `"programmatic"` + The filename of the file cited. - - `top_p: number` + - `index: number` - An alternative to sampling with temperature, called nucleus sampling, - where the model considers the results of the tokens with top_p probability - mass. So 0.1 means only the tokens comprising the top 10% probability mass - are considered. + The index of the file in the list of files. - We generally recommend altering this or `temperature` but not both. + - `type: "file_citation"` - - `background: optional boolean` + The type of the file citation. Always `file_citation`. - Whether to run the model response in the background. - [Learn more](/docs/guides/background). + - `"file_citation"` - - `completed_at: optional number` + - `URLCitation object { end_index, start_index, title, 2 more }` - Unix timestamp (in seconds) of when this Response was completed. - Only present when the status is `completed`. + A citation for a web resource used to generate a model response. - - `conversation: optional object { id }` + - `end_index: number` - The conversation that this response belonged to. Input items and output items from this response were automatically added to this conversation. + The index of the last character of the URL citation in the message. - - `id: string` + - `start_index: number` - The unique ID of the conversation that this response was associated with. + The index of the first character of the URL citation in the message. - - `max_output_tokens: optional number` + - `title: string` - An upper bound for the number of tokens that can be generated for a response, including visible output tokens and [reasoning tokens](/docs/guides/reasoning). + The title of the web resource. - - `max_tool_calls: optional number` + - `type: "url_citation"` - The maximum number of total calls to built-in tools that can be processed in a response. This maximum number applies across all built-in tool calls, not per individual tool. Any further attempts to call a tool by the model will be ignored. + The type of the URL citation. Always `url_citation`. - - `moderation: optional object { input, output }` + - `"url_citation"` - Moderation results for the response input and output, if moderated completions were requested. + - `url: string` - - `input: object { categories, category_applied_input_types, category_scores, 3 more } or object { code, message, type }` + The URL of the web resource. - Moderation for the response input. + - `ContainerFileCitation object { container_id, end_index, file_id, 3 more }` - - `ModerationResult object { categories, category_applied_input_types, category_scores, 3 more }` + A citation for a container file used to generate a model response. - A moderation result produced for the response input or output. + - `container_id: string` - - `categories: map[boolean]` + The ID of the container file. - A dictionary of moderation categories to booleans, True if the input is flagged under this category. + - `end_index: number` - - `category_applied_input_types: map[array of "text" or "image"]` + The index of the last character of the container file citation in the message. - Which modalities of input are reflected by the score for each category. + - `file_id: string` - - `"text"` + The ID of the file. - - `"image"` + - `filename: string` - - `category_scores: map[number]` + The filename of the container file cited. - A dictionary of moderation categories to scores. + - `start_index: number` - - `flagged: boolean` + The index of the first character of the container file citation in the message. - A boolean indicating whether the content was flagged by any category. + - `type: "container_file_citation"` - - `model: string` + The type of the container file citation. Always `container_file_citation`. - The moderation model that produced this result. + - `"container_file_citation"` - - `type: "moderation_result"` + - `FilePath object { file_id, index, type }` - The object type, which was always `moderation_result` for successful moderation results. + A path to a file. - - `"moderation_result"` + - `file_id: string` - - `Error object { code, message, type }` + The ID of the file. - An error produced while attempting moderation for the response input or output. + - `index: number` - - `code: string` + The index of the file in the list of files. - The error code. + - `type: "file_path"` - - `message: string` + The type of the file path. Always `file_path`. - The error message. + - `"file_path"` - - `type: "error"` + - `logprobs: array of object { token, bytes, logprob, top_logprobs }` - The object type, which was always `error` for moderation failures. + - `token: string` - - `"error"` + - `bytes: array of number` - - `output: object { categories, category_applied_input_types, category_scores, 3 more } or object { code, message, type }` + - `logprob: number` - Moderation for the response output. + - `top_logprobs: array of object { token, bytes, logprob }` - - `ModerationResult object { categories, category_applied_input_types, category_scores, 3 more }` + - `token: string` - A moderation result produced for the response input or output. + - `bytes: array of number` - - `categories: map[boolean]` + - `logprob: number` - A dictionary of moderation categories to booleans, True if the input is flagged under this category. + - `text: string` - - `category_applied_input_types: map[array of "text" or "image"]` + The text output from the model. - Which modalities of input are reflected by the score for each category. + - `type: "output_text"` - - `"text"` + The type of the output text. Always `output_text`. - - `"image"` + - `"output_text"` - - `category_scores: map[number]` + - `ResponseOutputRefusal object { refusal, type }` - A dictionary of moderation categories to scores. + A refusal from the model. - - `flagged: boolean` + - `refusal: string` - A boolean indicating whether the content was flagged by any category. + The refusal explanation from the model. - - `model: string` + - `type: "refusal"` - The moderation model that produced this result. + The type of the refusal. Always `refusal`. - - `type: "moderation_result"` + - `"refusal"` - The object type, which was always `moderation_result` for successful moderation results. + - `role: "assistant"` - - `"moderation_result"` + The role of the output message. Always `assistant`. - - `Error object { code, message, type }` + - `"assistant"` - An error produced while attempting moderation for the response input or output. + - `status: "in_progress" or "completed" or "incomplete"` - - `code: string` + The status of the message input. One of `in_progress`, `completed`, or + `incomplete`. Populated when input items are returned via API. - The error code. + - `"in_progress"` - - `message: string` + - `"completed"` - The error message. + - `"incomplete"` - - `type: "error"` + - `type: "message"` - The object type, which was always `error` for moderation failures. + The type of the output message. Always `message`. - - `"error"` + - `"message"` - - `output_text: optional string` + - `phase: optional "commentary" or "final_answer"` - SDK-only convenience property that contains the aggregated text output - from all `output_text` items in the `output` array, if any are present. - Supported in the Python and JavaScript SDKs. + 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. - - `previous_response_id: optional string` + - `"commentary"` - The unique ID of the previous response to the model. Use this to - create multi-turn conversations. Learn more about - [conversation state](/docs/guides/conversation-state). Cannot be used in conjunction with `conversation`. + - `"final_answer"` - - `prompt: optional ResponsePrompt` + - `FileSearchCall object { id, queries, status, 2 more }` - Reference to a prompt template and its variables. - [Learn more](/docs/guides/text?api-mode=responses#reusable-prompts). + 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 identifier of the prompt template to use. - - - `variables: optional map[string or ResponseInputText or ResponseInputImage or ResponseInputFile]` + The unique ID of the file search tool call. - Optional map of values to substitute in for variables in your - prompt. The substitution values can either be strings, or other - Response input types like images or files. + - `queries: array of string` - - `string` + The queries used to search for files. - - `ResponseInputText object { text, type, prompt_cache_breakpoint }` + - `status: "in_progress" or "searching" or "completed" or 2 more` - A text input to the model. + The status of the file search tool call. One of `in_progress`, + `searching`, `incomplete` or `failed`, - - `ResponseInputImage object { detail, type, file_id, 2 more }` + - `"in_progress"` - An image input to the model. Learn about [image inputs](/docs/guides/vision). + - `"searching"` - - `ResponseInputFile object { type, detail, file_data, 4 more }` + - `"completed"` - A file input to the model. + - `"incomplete"` - - `version: optional string` + - `"failed"` - Optional version of the prompt template. + - `type: "file_search_call"` - - `prompt_cache_key: optional string` + The type of the file search tool call. Always `file_search_call`. - Used by OpenAI to cache responses for similar requests to optimize your cache hit rates. Replaces the `user` field. [Learn more](/docs/guides/prompt-caching). + - `"file_search_call"` - - `prompt_cache_options: optional object { mode, ttl }` + - `results: optional array of object { attributes, file_id, filename, 2 more }` - The prompt-caching options that were applied to the response. Supported for `gpt-5.6` and later models. + The results of the file search tool call. - - `mode: "implicit" or "explicit"` + - `attributes: optional map[string or number or boolean]` - Whether implicit prompt-cache breakpoints were enabled. + 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. - - `"implicit"` + - `string` - - `"explicit"` + - `number` - - `ttl: "30m"` + - `boolean` - The minimum lifetime applied to each cache breakpoint. + - `file_id: optional string` - - `"30m"` + The unique ID of the file. - - `prompt_cache_retention: optional "in_memory" or "24h"` + - `filename: optional string` - Deprecated. Use `prompt_cache_options.ttl` instead. + The name of the file. - The retention policy for the prompt cache. Set to `24h` to enable extended prompt caching, which keeps cached prefixes active for longer, up to a maximum of 24 hours. [Learn more](/docs/guides/prompt-caching#prompt-cache-retention). - This field expresses a maximum retention policy, while - `prompt_cache_options.ttl` expresses a minimum cache lifetime. The two - fields are independent and do not interact. - For `gpt-5.5`, `gpt-5.5-pro`, and future models, only `24h` is supported. + - `score: optional number` - For older models that support both `in_memory` and `24h`, the default depends on your organization's data retention policy: + The relevance score of the file - a value between 0 and 1. - - Organizations without ZDR enabled default to `24h`. - - Organizations with ZDR enabled default to `in_memory` when `prompt_cache_retention` is not specified. + - `text: optional string` - - `"in_memory"` + The text that was retrieved from the file. - - `"24h"` + - `ComputerCall object { id, call_id, pending_safety_checks, 4 more }` - - `reasoning: optional Reasoning` + A tool call to a computer use tool. See the + [computer use guide](/docs/guides/tools-computer-use) for more information. - **gpt-5 and o-series models only** + - `id: string` - Configuration options for - [reasoning models](https://platform.openai.com/docs/guides/reasoning). + The unique ID of the computer call. - - `context: optional "auto" or "current_turn" or "all_turns"` + - `call_id: string` - Controls which reasoning items are rendered back to the model on later turns. - If omitted or set to `auto`, the model determines the context mode. The - `gpt-5.6` model family defaults to `all_turns`; earlier models default to - `current_turn`. + An identifier used when responding to the tool call with output. - When returned on a response, this is the effective reasoning context mode - used for the response. + - `pending_safety_checks: array of object { id, code, message }` - - `"auto"` + The pending safety checks for the computer call. - - `"current_turn"` + - `id: string` - - `"all_turns"` + The ID of the pending safety check. - - `effort: optional ReasoningEffort` + - `code: optional string` - Constrains effort on reasoning for reasoning models. Currently supported - values are `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max`. - Reducing reasoning effort can result in faster responses and fewer tokens - used on reasoning in a response. Not all reasoning models support every - value. See the - [reasoning guide](https://platform.openai.com/docs/guides/reasoning) - for model-specific support. + The type of the pending safety check. - - `"none"` + - `message: optional string` - - `"minimal"` + Details about the pending safety check. - - `"low"` + - `status: "in_progress" or "completed" or "incomplete"` - - `"medium"` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `"high"` + - `"in_progress"` - - `"xhigh"` + - `"completed"` - - `"max"` + - `"incomplete"` - - `generate_summary: optional "auto" or "concise" or "detailed"` + - `type: "computer_call"` - **Deprecated:** use `summary` instead. + The type of the computer call. Always `computer_call`. - A summary of the reasoning performed by the model. This can be - useful for debugging and understanding the model's reasoning process. - One of `auto`, `concise`, or `detailed`. + - `"computer_call"` - - `"auto"` + - `action: optional ComputerAction` - - `"concise"` + A click action. - - `"detailed"` + - `Click object { button, type, x, 2 more }` - - `mode: optional string or "standard" or "pro"` + A click action. - Controls the reasoning execution mode for the request. + - `button: "left" or "right" or "wheel" or 2 more` - When returned on a response, this is the effective execution mode. + Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. - - `string` + - `"left"` - - `"standard" or "pro"` + - `"right"` - Controls the reasoning execution mode for the request. + - `"wheel"` - When returned on a response, this is the effective execution mode. + - `"back"` - - `"standard"` + - `"forward"` - - `"pro"` + - `type: "click"` - - `summary: optional "auto" or "concise" or "detailed"` + Specifies the event type. For a click action, this property is always `click`. - A summary of the reasoning performed by the model. This can be - useful for debugging and understanding the model's reasoning process. - One of `auto`, `concise`, or `detailed`. + - `"click"` - `concise` is supported for `computer-use-preview` models and all reasoning models after `gpt-5`. + - `x: number` - - `"auto"` + The x-coordinate where the click occurred. - - `"concise"` + - `y: number` - - `"detailed"` + The y-coordinate where the click occurred. - - `safety_identifier: optional string` + - `keys: optional array of string` - A stable identifier used to help detect users of your application that may be violating OpenAI's usage policies. - The IDs should be a string that uniquely identifies each user, with a maximum length of 64 characters. We recommend hashing their username or email address, in order to avoid sending us any identifying information. [Learn more](/docs/guides/safety-best-practices#safety-identifiers). + The keys being held while clicking. - - `service_tier: optional "auto" or "default" or "flex" or 2 more` + - `DoubleClick object { keys, type, x, y }` - Specifies the processing type used for serving the request. + A double click action. - - If set to 'auto', then the request will be processed with the service tier configured in the Project settings. Unless otherwise configured, the Project will use 'default'. - - If set to 'default', then the request will be processed with the standard pricing and performance for the selected model. - - If set to '[flex](/docs/guides/flex-processing)' or '[priority](https://openai.com/api-priority-processing/)', then the request will be processed with the corresponding service tier. - - When not set, the default behavior is 'auto'. + - `keys: array of string` - When the `service_tier` parameter is set, the response body will include the `service_tier` value based on the processing mode actually used to serve the request. This response value may be different from the value set in the parameter. + The keys being held while double-clicking. - - `"auto"` + - `type: "double_click"` - - `"default"` + Specifies the event type. For a double click action, this property is always set to `double_click`. - - `"flex"` + - `"double_click"` - - `"scale"` + - `x: number` - - `"priority"` + The x-coordinate where the double click occurred. - - `status: optional ResponseStatus` + - `y: number` - The status of the response generation. One of `completed`, `failed`, - `in_progress`, `cancelled`, `queued`, or `incomplete`. + The y-coordinate where the double click occurred. - - `"completed"` + - `Drag object { path, type, keys }` - - `"failed"` + A drag action. - - `"in_progress"` + - `path: array of object { x, y }` - - `"cancelled"` + An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg - - `"queued"` + ``` + [ + { x: 100, y: 200 }, + { x: 200, y: 300 } + ] + ``` - - `"incomplete"` + - `x: number` - - `text: optional ResponseTextConfig` + The x-coordinate. - Configuration options for a text response from the model. Can be plain - text or structured JSON data. Learn more: + - `y: number` - - [Text inputs and outputs](/docs/guides/text) - - [Structured Outputs](/docs/guides/structured-outputs) + The y-coordinate. - - `format: optional ResponseFormatTextConfig` + - `type: "drag"` - An object specifying the format that the model must output. + Specifies the event type. For a drag action, this property is always set to `drag`. - Configuring `{ "type": "json_schema" }` enables Structured Outputs, - which ensures the model will match your supplied JSON schema. Learn more in the - [Structured Outputs guide](/docs/guides/structured-outputs). + - `"drag"` - The default format is `{ "type": "text" }` with no additional options. + - `keys: optional array of string` - **Not recommended for gpt-4o and newer models:** + The keys being held while dragging the mouse. - Setting to `{ "type": "json_object" }` enables the older JSON mode, which - ensures the message the model generates is valid JSON. Using `json_schema` - is preferred for models that support it. + - `Keypress object { keys, type }` - - `ResponseFormatText object { type }` + A collection of keypresses the model would like to perform. - Default response format. Used to generate text responses. + - `keys: array of string` - - `type: "text"` + The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. - The type of response format being defined. Always `text`. + - `type: "keypress"` - - `"text"` + Specifies the event type. For a keypress action, this property is always set to `keypress`. - - `ResponseFormatTextJSONSchemaConfig object { name, schema, type, 2 more }` + - `"keypress"` - JSON Schema response format. Used to generate structured JSON responses. - Learn more about [Structured Outputs](/docs/guides/structured-outputs). + - `Move object { type, x, y, keys }` - - `name: string` + A mouse move action. - The name of the response format. Must be a-z, A-Z, 0-9, or contain - underscores and dashes, with a maximum length of 64. + - `type: "move"` - - `schema: map[unknown]` + Specifies the event type. For a move action, this property is always set to `move`. - The schema for the response format, described as a JSON Schema object. - Learn how to build JSON schemas [here](https://json-schema.org/). + - `"move"` - - `type: "json_schema"` + - `x: number` - The type of response format being defined. Always `json_schema`. + The x-coordinate to move to. - - `"json_schema"` + - `y: number` - - `description: optional string` + The y-coordinate to move to. - A description of what the response format is for, used by the model to - determine how to respond in the format. + - `keys: optional array of string` - - `strict: optional boolean` + The keys being held while moving the mouse. - Whether to enable strict schema adherence when generating the output. - If set to true, the model will always follow the exact schema defined - in the `schema` field. Only a subset of JSON Schema is supported when - `strict` is `true`. To learn more, read the [Structured Outputs - guide](/docs/guides/structured-outputs). + - `Screenshot object { type }` - - `ResponseFormatJSONObject object { type }` + A screenshot action. - JSON object response format. An older method of generating JSON responses. - Using `json_schema` is recommended for models that support it. Note that the - model will not generate JSON without a system or user message instructing it - to do so. + - `type: "screenshot"` - - `type: "json_object"` + Specifies the event type. For a screenshot action, this property is always set to `screenshot`. - The type of response format being defined. Always `json_object`. + - `"screenshot"` - - `"json_object"` + - `Scroll object { scroll_x, scroll_y, type, 3 more }` - - `verbosity: optional "low" or "medium" or "high"` + A scroll action. - Constrains the verbosity of the model's response. Lower values will result in - more concise responses, while higher values will result in more verbose responses. - Currently supported values are `low`, `medium`, and `high`. The default is - `medium`. + - `scroll_x: number` - - `"low"` + The horizontal scroll distance. - - `"medium"` + - `scroll_y: number` - - `"high"` + The vertical scroll distance. - - `top_logprobs: optional number` + - `type: "scroll"` - An integer between 0 and 20 specifying the maximum number of most likely - tokens to return at each token position, each with an associated log - probability. In some cases, the number of returned tokens may be fewer than - requested. + Specifies the event type. For a scroll action, this property is always set to `scroll`. - - `truncation: optional "auto" or "disabled"` + - `"scroll"` - The truncation strategy to use for the model response. + - `x: number` - - `auto`: If the input to this Response exceeds - the model's context window size, the model will truncate the - response to fit the context window by dropping items from the beginning of the conversation. - - `disabled` (default): If the input size will exceed the context window - size for a model, the request will fail with a 400 error. + The x-coordinate where the scroll occurred. - - `"auto"` + - `y: number` - - `"disabled"` + The y-coordinate where the scroll occurred. - - `usage: optional ResponseUsage` + - `keys: optional array of string` - Represents token usage details including input tokens, output tokens, - a breakdown of output tokens, and the total tokens used. + The keys being held while scrolling. - - `input_tokens: number` + - `Type object { text, type }` - The number of input tokens. + An action to type in text. - - `input_tokens_details: object { cache_write_tokens, cached_tokens }` + - `text: string` - A detailed breakdown of the input tokens. + The text to type. - - `cache_write_tokens: number` + - `type: "type"` - The number of input tokens that were written to the cache. + Specifies the event type. For a type action, this property is always set to `type`. - - `cached_tokens: number` + - `"type"` - The number of tokens that were retrieved from the cache. - [More on prompt caching](/docs/guides/prompt-caching). + - `Wait object { type }` - - `output_tokens: number` + A wait action. - The number of output tokens. + - `type: "wait"` - - `output_tokens_details: object { reasoning_tokens }` + Specifies the event type. For a wait action, this property is always set to `wait`. - A detailed breakdown of the output tokens. + - `"wait"` - - `reasoning_tokens: number` + - `actions: optional ComputerActionList` - The number of reasoning tokens. + Flattened batched actions for `computer_use`. Each action includes an + `type` discriminator and action-specific fields. - - `total_tokens: number` + - `Click object { button, type, x, 2 more }` - The total number of tokens used. + A click action. - - `user: optional string` + - `DoubleClick object { keys, type, x, y }` - This field is being replaced by `safety_identifier` and `prompt_cache_key`. Use `prompt_cache_key` instead to maintain caching optimizations. - A stable identifier for your end-users. - Used to boost cache hit rates by better bucketing similar requests and to help OpenAI detect and prevent abuse. [Learn more](/docs/guides/safety-best-practices#safety-identifiers). + A double click action. -### Example + - `Drag object { path, type, keys }` -```http -curl https://api.openai.com/v1/responses/$RESPONSE_ID/cancel \ - -X POST \ - -H "Authorization: Bearer $OPENAI_API_KEY" -``` + A drag action. -#### Response + - `Keypress object { keys, type }` -```json -{ - "id": "id", - "created_at": 0, - "error": { - "code": "server_error", - "message": "message" - }, - "incomplete_details": { - "reason": "max_output_tokens" - }, - "instructions": "string", - "metadata": { - "foo": "string" - }, - "model": "gpt-5.1", - "object": "response", - "output": [ - { - "id": "id", - "content": [ - { - "annotations": [ - { - "file_id": "file_id", - "filename": "filename", - "index": 0, - "type": "file_citation" - } - ], - "logprobs": [ - { - "token": "token", - "bytes": [ - 0 - ], - "logprob": 0, - "top_logprobs": [ - { - "token": "token", - "bytes": [ - 0 - ], - "logprob": 0 - } - ] - } - ], - "text": "text", - "type": "output_text" - } - ], - "role": "assistant", - "status": "in_progress", - "type": "message", - "phase": "commentary" - } - ], - "parallel_tool_calls": true, - "temperature": 1, - "tool_choice": "none", - "tools": [ - { - "name": "name", - "parameters": { - "foo": "bar" - }, - "strict": true, - "type": "function", - "allowed_callers": [ - "direct" - ], - "defer_loading": true, - "description": "description", - "output_schema": { - "foo": "bar" - } - } - ], - "top_p": 1, - "background": true, - "completed_at": 0, - "conversation": { - "id": "id" - }, - "max_output_tokens": 0, - "max_tool_calls": 0, - "moderation": { - "input": { - "categories": { - "foo": true - }, - "category_applied_input_types": { - "foo": [ - "text" - ] - }, - "category_scores": { - "foo": 0 - }, - "flagged": true, - "model": "model", - "type": "moderation_result" - }, - "output": { - "categories": { - "foo": true - }, - "category_applied_input_types": { - "foo": [ - "text" - ] - }, - "category_scores": { - "foo": 0 - }, - "flagged": true, - "model": "model", - "type": "moderation_result" - } - }, - "output_text": "output_text", - "previous_response_id": "previous_response_id", - "prompt": { - "id": "id", - "variables": { - "foo": "string" - }, - "version": "version" - }, - "prompt_cache_key": "prompt-cache-key-1234", - "prompt_cache_options": { - "mode": "implicit", - "ttl": "30m" - }, - "prompt_cache_retention": "in_memory", - "reasoning": { - "context": "auto", - "effort": "none", - "generate_summary": "auto", - "mode": "standard", - "summary": "auto" - }, - "safety_identifier": "safety-identifier-1234", - "service_tier": "auto", - "status": "completed", - "text": { - "format": { - "type": "text" - }, - "verbosity": "low" - }, - "top_logprobs": 0, - "truncation": "auto", - "usage": { - "input_tokens": 0, - "input_tokens_details": { - "cache_write_tokens": 0, - "cached_tokens": 0 - }, - "output_tokens": 0, - "output_tokens_details": { - "reasoning_tokens": 0 - }, - "total_tokens": 0 - }, - "user": "user-1234" -} -``` + A collection of keypresses the model would like to perform. -### Example + - `Move object { type, x, y, keys }` -```http -curl -X POST https://api.openai.com/v1/responses/resp_123/cancel \ - -H "Content-Type: application/json" \ - -H "Authorization: Bearer $OPENAI_API_KEY" -``` + A mouse move action. -#### Response + - `Screenshot object { type }` -```json -{ - "id": "resp_67cb71b351908190a308f3859487620d06981a8637e6bc44", - "object": "response", - "created_at": 1741386163, - "status": "cancelled", - "background": true, - "completed_at": null, - "error": null, - "incomplete_details": null, - "instructions": null, - "max_output_tokens": null, - "model": "gpt-4o-2024-08-06", - "output": [ - { - "type": "message", - "id": "msg_67cb71b3c2b0819084d481baaaf148f206981a8637e6bc44", - "status": "in_progress", - "role": "assistant", - "content": [ - { - "type": "output_text", - "text": "Silent circuits hum, \nThoughts emerge in data streams— \nDigital dawn breaks.", - "annotations": [] - } - ] - } - ], - "parallel_tool_calls": true, - "previous_response_id": null, - "reasoning": { - "effort": null, - "summary": null - }, - "store": true, - "temperature": 1.0, - "text": { - "format": { - "type": "text" - } - }, - "tool_choice": "auto", - "tools": [], - "top_p": 1.0, - "truncation": "disabled", - "usage": null, - "user": null, - "metadata": {} -} -``` + A screenshot action. + + - `Scroll object { scroll_x, scroll_y, type, 3 more }` -## Compact a response + A scroll action. -**post** `/responses/compact` + - `Type object { text, type }` -Compact a conversation. Returns a compacted response object. + An action to type in text. -Learn when and how to compact long-running conversations in the [conversation state guide](/docs/guides/conversation-state#managing-the-context-window). For ZDR-compatible compaction details, see [Compaction (advanced)](/docs/guides/conversation-state#compaction-advanced). + - `Wait object { type }` -### Body Parameters + A wait action. -- `model: "gpt-5.6-sol" or "gpt-5.6-terra" or "gpt-5.6-luna" or 92 more or string` + - `ComputerCallOutput object { call_id, output, type, 3 more }` - Model ID used to generate the response, like `gpt-5` or `o3`. OpenAI offers a wide range of models with different capabilities, performance characteristics, and price points. Refer to the [model guide](/docs/models) to browse and compare available models. + The output of a computer tool call. - - `"gpt-5.6-sol" or "gpt-5.6-terra" or "gpt-5.6-luna" or 92 more` + - `call_id: string` - Model ID used to generate the response, like `gpt-5` or `o3`. OpenAI offers a wide range of models with different capabilities, performance characteristics, and price points. Refer to the [model guide](/docs/models) to browse and compare available models. + The ID of the computer tool call that produced the output. - - `"gpt-5.6-sol"` + - `output: ResponseComputerToolCallOutputScreenshot` - - `"gpt-5.6-terra"` + A computer screenshot image used with the computer use tool. - - `"gpt-5.6-luna"` + - `type: "computer_screenshot"` - - `"gpt-5.4"` + Specifies the event type. For a computer screenshot, this property is + always set to `computer_screenshot`. - - `"gpt-5.4-mini"` + - `"computer_screenshot"` - - `"gpt-5.4-nano"` + - `file_id: optional string` - - `"gpt-5.4-mini-2026-03-17"` + The identifier of an uploaded file that contains the screenshot. - - `"gpt-5.4-nano-2026-03-17"` + - `image_url: optional string` - - `"gpt-5.3-chat-latest"` + The URL of the screenshot image. - - `"gpt-5.2"` + - `type: "computer_call_output"` - - `"gpt-5.2-2025-12-11"` + The type of the computer tool call output. Always `computer_call_output`. - - `"gpt-5.2-chat-latest"` + - `"computer_call_output"` - - `"gpt-5.2-pro"` + - `id: optional string` - - `"gpt-5.2-pro-2025-12-11"` + The ID of the computer tool call output. - - `"gpt-5.1"` + - `acknowledged_safety_checks: optional array of object { id, code, message }` - - `"gpt-5.1-2025-11-13"` + The safety checks reported by the API that have been acknowledged by the developer. - - `"gpt-5.1-codex"` + - `id: string` - - `"gpt-5.1-mini"` + The ID of the pending safety check. - - `"gpt-5.1-chat-latest"` + - `code: optional string` - - `"gpt-5"` + The type of the pending safety check. - - `"gpt-5-mini"` + - `message: optional string` - - `"gpt-5-nano"` + Details about the pending safety check. - - `"gpt-5-2025-08-07"` + - `status: optional "in_progress" or "completed" or "incomplete"` - - `"gpt-5-mini-2025-08-07"` + The status of the message input. One of `in_progress`, `completed`, or `incomplete`. Populated when input items are returned via API. - - `"gpt-5-nano-2025-08-07"` + - `"in_progress"` - - `"gpt-5-chat-latest"` + - `"completed"` - - `"gpt-4.1"` + - `"incomplete"` - - `"gpt-4.1-mini"` + - `WebSearchCall object { id, action, status, type }` - - `"gpt-4.1-nano"` + The results of a web search tool call. See the + [web search guide](/docs/guides/tools-web-search) for more information. - - `"gpt-4.1-2025-04-14"` + - `id: string` - - `"gpt-4.1-mini-2025-04-14"` + The unique ID of the web search tool call. - - `"gpt-4.1-nano-2025-04-14"` + - `action: object { type, queries, query, sources } or object { type, url } or object { pattern, type, url }` - - `"o4-mini"` + 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). - - `"o4-mini-2025-04-16"` + - `Search object { type, queries, query, sources }` - - `"o3"` + Action type "search" - Performs a web search query. - - `"o3-2025-04-16"` + - `type: "search"` - - `"o3-mini"` + The action type. - - `"o3-mini-2025-01-31"` + - `"search"` - - `"o1"` + - `queries: optional array of string` - - `"o1-2024-12-17"` + The search queries. - - `"o1-preview"` + - `query: optional string` - - `"o1-preview-2024-09-12"` + The search query. - - `"o1-mini"` + - `sources: optional array of object { type, url }` - - `"o1-mini-2024-09-12"` + The sources used in the search. - - `"gpt-4o"` + - `type: "url"` - - `"gpt-4o-2024-11-20"` + The type of source. Always `url`. - - `"gpt-4o-2024-08-06"` + - `"url"` - - `"gpt-4o-2024-05-13"` + - `url: string` - - `"gpt-4o-audio-preview"` + The URL of the source. - - `"gpt-4o-audio-preview-2024-10-01"` + - `OpenPage object { type, url }` - - `"gpt-4o-audio-preview-2024-12-17"` + Action type "open_page" - Opens a specific URL from search results. - - `"gpt-4o-audio-preview-2025-06-03"` + - `type: "open_page"` - - `"gpt-4o-mini-audio-preview"` + The action type. - - `"gpt-4o-mini-audio-preview-2024-12-17"` + - `"open_page"` - - `"gpt-4o-search-preview"` + - `url: optional string` - - `"gpt-4o-mini-search-preview"` + The URL opened by the model. - - `"gpt-4o-search-preview-2025-03-11"` + - `FindInPage object { pattern, type, url }` - - `"gpt-4o-mini-search-preview-2025-03-11"` + Action type "find_in_page": Searches for a pattern within a loaded page. - - `"chatgpt-4o-latest"` + - `pattern: string` - - `"codex-mini-latest"` + The pattern or text to search for within the page. - - `"gpt-4o-mini"` + - `type: "find_in_page"` - - `"gpt-4o-mini-2024-07-18"` + The action type. - - `"gpt-4-turbo"` + - `"find_in_page"` - - `"gpt-4-turbo-2024-04-09"` + - `url: string` - - `"gpt-4-0125-preview"` + The URL of the page searched for the pattern. - - `"gpt-4-turbo-preview"` + - `status: "in_progress" or "searching" or "completed" or "failed"` - - `"gpt-4-1106-preview"` + The status of the web search tool call. - - `"gpt-4-vision-preview"` + - `"in_progress"` - - `"gpt-4"` + - `"searching"` - - `"gpt-4-0314"` + - `"completed"` - - `"gpt-4-0613"` + - `"failed"` - - `"gpt-4-32k"` + - `type: "web_search_call"` - - `"gpt-4-32k-0314"` + The type of the web search tool call. Always `web_search_call`. - - `"gpt-4-32k-0613"` + - `"web_search_call"` - - `"gpt-3.5-turbo"` + - `FunctionCall object { arguments, call_id, name, 5 more }` - - `"gpt-3.5-turbo-16k"` + A tool call to run a function. See the + [function calling guide](/docs/guides/function-calling) for more information. - - `"gpt-3.5-turbo-0301"` + - `arguments: string` - - `"gpt-3.5-turbo-0613"` + A JSON string of the arguments to pass to the function. - - `"gpt-3.5-turbo-1106"` + - `call_id: string` - - `"gpt-3.5-turbo-0125"` + The unique ID of the function tool call generated by the model. - - `"gpt-3.5-turbo-16k-0613"` + - `name: string` - - `"o1-pro"` + The name of the function to run. - - `"o1-pro-2025-03-19"` + - `type: "function_call"` - - `"o3-pro"` + The type of the function tool call. Always `function_call`. - - `"o3-pro-2025-06-10"` + - `"function_call"` - - `"o3-deep-research"` + - `id: optional string` - - `"o3-deep-research-2025-06-26"` + The unique ID of the function tool call. - - `"o4-mini-deep-research"` + - `caller: optional object { type } or object { caller_id, type }` - - `"o4-mini-deep-research-2025-06-26"` + The execution context that produced this tool call. - - `"computer-use-preview"` + - `Direct object { type }` - - `"computer-use-preview-2025-03-11"` + - `type: "direct"` - - `"gpt-5-codex"` + - `"direct"` - - `"gpt-5-pro"` + - `Program object { caller_id, type }` - - `"gpt-5-pro-2025-10-06"` + - `caller_id: string` - - `"gpt-5.1-codex-max"` + The call ID of the program item that produced this tool call. - - `string` + - `type: "program"` -- `input: optional string or array of EasyInputMessage or object { content, role, status, type } or ResponseOutputMessage or 29 more` + - `"program"` - Text, image, or file inputs to the model, used to generate a response + - `namespace: optional string` - - `string` + The namespace of the function to run. - A text input to the model, equivalent to a text input with the `user` role. + - `status: optional "in_progress" or "completed" or "incomplete"` - - `array of EasyInputMessage or object { content, role, status, type } or ResponseOutputMessage or 29 more` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - A list of one or many input items to the model, containing different content types. + - `"in_progress"` - - `EasyInputMessage object { content, role, phase, type }` + - `"completed"` - 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. + - `"incomplete"` - - `content: string or ResponseInputMessageContentList` + - `FunctionCallOutput object { call_id, output, type, 3 more }` - Text, image, or audio input to the model, used to generate a response. - Can also contain previous assistant responses. + The output of a function tool call. - - `TextInput = string` + - `call_id: string` - A text input to the model. + The unique ID of the function tool call generated by the model. - - `ResponseInputMessageContentList = array of ResponseInputContent` + - `output: string or array of ResponseInputTextContent or ResponseInputImageContent or ResponseInputFileContent` - A list of one or many input items to the model, containing different content - types. + Text, image, or file output of the function tool call. - - `ResponseInputText object { text, type, prompt_cache_breakpoint }` + - `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, prompt_cache_breakpoint }` A text input to the model. @@ -34562,11 +34595,17 @@ Learn when and how to compact long-running conversations in the [conversation st - `"explicit"` - - `ResponseInputImage object { detail, type, file_id, 2 more }` + - `ResponseInputImageContent object { type, detail, file_id, 2 more }` - An image input to the model. Learn about [image inputs](/docs/guides/vision). + An image input to the model. Learn about [image inputs](/docs/guides/vision) - - `detail: "low" or "high" or "auto" or "original"` + - `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`. @@ -34578,12 +34617,6 @@ Learn when and how to compact long-running conversations in the [conversation st - `"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. @@ -34602,7 +34635,7 @@ Learn when and how to compact long-running conversations in the [conversation st - `"explicit"` - - `ResponseInputFile object { type, detail, file_data, 4 more }` + - `ResponseInputFileContent object { type, detail, file_data, 4 more }` A file input to the model. @@ -34624,7 +34657,7 @@ Learn when and how to compact long-running conversations in the [conversation st - `file_data: optional string` - The content of the file to be sent to the model. + The base64-encoded data of the file to be sent to the model. - `file_id: optional string` @@ -34648,60 +34681,81 @@ Learn when and how to compact long-running conversations in the [conversation st - `"explicit"` - - `role: "user" or "assistant" or "system" or "developer"` + - `type: "function_call_output"` - The role of the message input. One of `user`, `assistant`, `system`, or - `developer`. + The type of the function tool call output. Always `function_call_output`. - - `"user"` + - `"function_call_output"` - - `"assistant"` + - `id: optional string` - - `"system"` + The unique ID of the function tool call output. Populated when this item is returned via API. - - `"developer"` + - `caller: optional object { type } or object { caller_id, type }` - - `phase: optional "commentary" or "final_answer"` + The execution context that produced this tool call. - 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. + - `Direct object { type }` - - `"commentary"` + - `type: "direct"` - - `"final_answer"` + The caller type. Always `direct`. - - `type: optional "message"` + - `"direct"` - The type of the message input. Always `message`. + - `Program object { caller_id, type }` - - `"message"` + - `caller_id: string` - - `Message object { content, role, status, type }` + The call ID of the program item that produced this tool call. - 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. + - `type: "program"` - - `content: ResponseInputMessageContentList` + The caller type. Always `program`. - A list of one or many input items to the model, containing different content - types. + - `"program"` - - `role: "user" or "system" or "developer"` + - `status: optional "in_progress" or "completed" or "incomplete"` - The role of the message input. One of `user`, `system`, or `developer`. + The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. - - `"user"` + - `"in_progress"` - - `"system"` + - `"completed"` - - `"developer"` + - `"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 item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + The status of the tool search call. - `"in_progress"` @@ -34709,961 +34763,1079 @@ Learn when and how to compact long-running conversations in the [conversation st - `"incomplete"` - - `type: optional "message"` + - `ToolSearchOutput object { tools, type, id, 3 more }` - The type of the message input. Always set to `message`. + - `tools: array of object { name, parameters, strict, 5 more } or object { type, vector_store_ids, filters, 2 more } or object { type } or 13 more` - - `"message"` + The loaded tool definitions returned by the tool search output. - - `ResponseOutputMessage object { id, content, role, 3 more }` + - `Function object { name, parameters, strict, 5 more }` - An output message from 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). - - `id: string` + - `name: string` - The unique ID of the output message. + The name of the function to call. - - `content: array of ResponseOutputText or ResponseOutputRefusal` + - `parameters: map[unknown]` - The content of the output message. + A JSON schema object describing the parameters of the function. - - `ResponseOutputText object { annotations, logprobs, text, type }` + - `strict: boolean` - A text output from the model. + Whether strict parameter validation is enforced for this function tool. - - `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: "function"` - The annotations of the text output. + The type of the function tool. Always `function`. - - `FileCitation object { file_id, filename, index, type }` + - `"function"` - A citation to a file. + - `allowed_callers: optional array of "direct" or "programmatic"` - - `file_id: string` + The tool invocation context(s). - The ID of the file. + - `"direct"` - - `filename: string` + - `"programmatic"` - The filename of the file cited. + - `defer_loading: optional boolean` - - `index: number` + Whether this function is deferred and loaded via tool search. - The index of the file in the list of files. + - `description: optional string` + + A description of the function. Used by the model to determine whether or not to call the function. + + - `output_schema: optional map[unknown]` + + A JSON schema object describing the JSON value encoded in string outputs for this function. + + - `FileSearch object { type, vector_store_ids, filters, 2 more }` + + A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). + + - `type: "file_search"` + + The type of the file search tool. Always `file_search`. + + - `"file_search"` + + - `vector_store_ids: array of string` + + The IDs of the vector stores to search. + + - `filters: optional ComparisonFilter or CompoundFilter` + + A filter to apply. + + - `ComparisonFilter object { key, type, value }` + + A filter used to compare a specified attribute key to a given value using a defined comparison operation. + + - `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. - - `type: "file_citation"` + - `hybrid_search: optional object { embedding_weight, text_weight }` - The type of the file citation. Always `file_citation`. + Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. - - `"file_citation"` + - `embedding_weight: number` - - `URLCitation object { end_index, start_index, title, 2 more }` + The weight of the embedding in the reciprocal ranking fusion. - A citation for a web resource used to generate a model response. + - `text_weight: number` - - `end_index: number` + The weight of the text in the reciprocal ranking fusion. - The index of the last character of the URL citation in the message. + - `ranker: optional "auto" or "default-2024-11-15"` - - `start_index: number` + The ranker to use for the file search. - The index of the first character of the URL citation in the message. + - `"auto"` - - `title: string` + - `"default-2024-11-15"` - The title of the web resource. + - `score_threshold: optional number` - - `type: "url_citation"` + The score threshold for the file search, a number between 0 and 1. Numbers closer to 1 will attempt to return only the most relevant results, but may return fewer results. - The type of the URL citation. Always `url_citation`. + - `Computer object { type }` - - `"url_citation"` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `url: string` + - `type: "computer"` - The URL of the web resource. + The type of the computer tool. Always `computer`. - - `ContainerFileCitation object { container_id, end_index, file_id, 3 more }` + - `"computer"` - A citation for a container file used to generate a model response. + - `ComputerUsePreview object { display_height, display_width, environment, type }` - - `container_id: 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 container file. + - `display_height: number` - - `end_index: number` + The height of the computer display. - The index of the last character of the container file citation in the message. + - `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` - - `filename: string` + The type of computer environment to control. - The filename of the container file cited. + - `"windows"` - - `start_index: number` + - `"mac"` - The index of the first character of the container file citation in the message. + - `"linux"` - - `type: "container_file_citation"` + - `"ubuntu"` - The type of the container file citation. Always `container_file_citation`. + - `"browser"` - - `"container_file_citation"` + - `type: "computer_use_preview"` - - `FilePath object { file_id, index, type }` + The type of the computer use tool. Always `computer_use_preview`. - A path to a file. + - `"computer_use_preview"` - - `file_id: string` + - `WebSearch object { type, filters, search_context_size, user_location }` - The ID of the file. + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](/docs/guides/tools-web-search). - - `index: number` + - `type: "web_search" or "web_search_2025_08_26"` - The index of the file in the list of files. + The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. - - `type: "file_path"` + - `"web_search"` - The type of the file path. Always `file_path`. + - `"web_search_2025_08_26"` - - `"file_path"` + - `filters: optional object { allowed_domains }` - - `logprobs: array of object { token, bytes, logprob, top_logprobs }` + Filters for the search. - - `token: string` + - `allowed_domains: optional array of string` - - `bytes: array of number` + Allowed domains for the search. If not provided, all domains are allowed. + Subdomains of the provided domains are allowed as well. - - `logprob: number` + Example: `["pubmed.ncbi.nlm.nih.gov"]` - - `top_logprobs: array of object { token, bytes, logprob }` + - `search_context_size: optional "low" or "medium" or "high"` - - `token: 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. - - `bytes: array of number` + - `"low"` - - `logprob: number` + - `"medium"` - - `text: string` + - `"high"` - The text output from the model. + - `user_location: optional object { city, country, region, 2 more }` - - `type: "output_text"` + The approximate location of the user. - The type of the output text. Always `output_text`. + - `city: optional string` - - `"output_text"` + Free text input for the city of the user, e.g. `San Francisco`. - - `ResponseOutputRefusal object { refusal, type }` + - `country: optional string` - A refusal from the model. + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - - `refusal: string` + - `region: optional string` - The refusal explanation from the model. + Free text input for the region of the user, e.g. `California`. - - `type: "refusal"` + - `timezone: optional string` - The type of the refusal. Always `refusal`. + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - - `"refusal"` + - `type: optional "approximate"` - - `role: "assistant"` + The type of location approximation. Always `approximate`. - The role of the output message. Always `assistant`. + - `"approximate"` - - `"assistant"` + - `Mcp object { server_label, type, allowed_callers, 9 more }` - - `status: "in_progress" or "completed" or "incomplete"` + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](/docs/guides/tools-remote-mcp). - The status of the message input. One of `in_progress`, `completed`, or - `incomplete`. Populated when input items are returned via API. + - `server_label: string` - - `"in_progress"` + A label for this MCP server, used to identify it in tool calls. - - `"completed"` + - `type: "mcp"` - - `"incomplete"` + The type of the MCP tool. Always `mcp`. - - `type: "message"` + - `"mcp"` - The type of the output message. Always `message`. + - `allowed_callers: optional array of "direct" or "programmatic"` - - `"message"` + The tool invocation context(s). - - `phase: optional "commentary" or "final_answer"` + - `"direct"` - 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. + - `"programmatic"` - - `"commentary"` + - `allowed_tools: optional array of string or object { read_only, tool_names }` - - `"final_answer"` + List of allowed tool names or a filter object. - - `FileSearchCall object { id, queries, status, 2 more }` + - `McpAllowedTools = array of string` - The results of a file search tool call. See the - [file search guide](/docs/guides/tools-file-search) for more information. + A string array of allowed tool names - - `id: string` + - `McpToolFilter object { read_only, tool_names }` - The unique ID of the file search tool call. + A filter object to specify which tools are allowed. - - `queries: array of string` + - `read_only: optional boolean` - The queries used to search for files. + 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: "in_progress" or "searching" or "completed" or 2 more` + - `tool_names: optional array of string` - The status of the file search tool call. One of `in_progress`, - `searching`, `incomplete` or `failed`, + List of allowed tool names. - - `"in_progress"` + - `authorization: optional string` - - `"searching"` + 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. - - `"completed"` + - `connector_id: optional "connector_dropbox" or "connector_gmail" or "connector_googlecalendar" or 5 more` - - `"incomplete"` + Identifier for service connectors, like those available in ChatGPT. One of + `server_url`, `connector_id`, or `tunnel_id` must be provided. Learn more + about service connectors [here](/docs/guides/tools-remote-mcp#connectors). - - `"failed"` + Currently supported `connector_id` values are: - - `type: "file_search_call"` + - 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 file search tool call. Always `file_search_call`. + - `"connector_dropbox"` - - `"file_search_call"` + - `"connector_gmail"` - - `results: optional array of object { attributes, file_id, filename, 2 more }` + - `"connector_googlecalendar"` - The results of the file search tool call. + - `"connector_googledrive"` - - `attributes: optional map[string or number or boolean]` + - `"connector_microsoftteams"` - 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. + - `"connector_outlookcalendar"` - - `string` + - `"connector_outlookemail"` - - `number` + - `"connector_sharepoint"` - - `boolean` + - `defer_loading: optional boolean` - - `file_id: optional string` + Whether this MCP tool is deferred and discovered via tool search. - The unique ID of the file. + - `headers: optional map[string]` - - `filename: optional string` + Optional HTTP headers to send to the MCP server. Use for authentication + or other purposes. - The name of the file. + - `require_approval: optional object { always, never } or "always" or "never"` - - `score: optional number` + Specify which of the MCP server's tools require approval. - The relevance score of the file - a value between 0 and 1. + - `McpToolApprovalFilter object { always, never }` - - `text: 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. - The text that was retrieved from the file. + - `always: optional object { read_only, tool_names }` - - `ComputerCall object { id, call_id, pending_safety_checks, 4 more }` + A filter object to specify which tools are allowed. - A tool call to a computer use tool. See the - [computer use guide](/docs/guides/tools-computer-use) for more information. + - `read_only: optional boolean` - - `id: string` + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. - The unique ID of the computer call. + - `tool_names: optional array of string` - - `call_id: string` + List of allowed tool names. - An identifier used when responding to the tool call with output. + - `never: optional object { read_only, tool_names }` - - `pending_safety_checks: array of object { id, code, message }` + A filter object to specify which tools are allowed. - The pending safety checks for the computer call. + - `read_only: optional boolean` - - `id: string` + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. - The ID of the pending safety check. + - `tool_names: optional array of string` - - `code: optional string` + List of allowed tool names. - The type of the pending safety check. + - `McpToolApprovalSetting = "always" or "never"` - - `message: optional string` + 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. - Details about the pending safety check. + - `"always"` - - `status: "in_progress" or "completed" or "incomplete"` + - `"never"` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `server_description: optional string` - - `"in_progress"` + Optional description of the MCP server, used to provide more context. - - `"completed"` + - `server_url: optional string` - - `"incomplete"` + The URL for the MCP server. One of `server_url`, `connector_id`, or + `tunnel_id` must be provided. - - `type: "computer_call"` + - `tunnel_id: optional string` - The type of the computer call. Always `computer_call`. + The Secure MCP Tunnel ID to use instead of a direct server URL. One of + `server_url`, `connector_id`, or `tunnel_id` must be provided. - - `"computer_call"` + - `CodeInterpreter object { container, type, allowed_callers }` - - `action: optional ComputerAction` + A tool that runs Python code to help generate a response to a prompt. - A click action. + - `container: string or object { type, file_ids, memory_limit, network_policy }` - - `Click object { button, type, x, 2 more }` + 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 click action. + - `string` - - `button: "left" or "right" or "wheel" or 2 more` + The container ID. - Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. + - `CodeInterpreterToolAuto object { type, file_ids, memory_limit, network_policy }` - - `"left"` + Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. - - `"right"` + - `type: "auto"` - - `"wheel"` + Always `auto`. - - `"back"` + - `"auto"` - - `"forward"` + - `file_ids: optional array of string` - - `type: "click"` + An optional list of uploaded files to make available to your code. - Specifies the event type. For a click action, this property is always `click`. + - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` - - `"click"` + The memory limit for the code interpreter container. - - `x: number` + - `"1g"` - The x-coordinate where the click occurred. + - `"4g"` - - `y: number` + - `"16g"` - The y-coordinate where the click occurred. + - `"64g"` - - `keys: optional array of string` + - `network_policy: optional ContainerNetworkPolicyDisabled or ContainerNetworkPolicyAllowlist` - The keys being held while clicking. + Network access policy for the container. - - `DoubleClick object { keys, type, x, y }` + - `ContainerNetworkPolicyDisabled object { type }` - A double click action. + - `type: "disabled"` - - `keys: array of string` + Disable outbound network access. Always `disabled`. - The keys being held while double-clicking. + - `"disabled"` - - `type: "double_click"` + - `ContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` - Specifies the event type. For a double click action, this property is always set to `double_click`. + - `allowed_domains: array of string` - - `"double_click"` + A list of allowed domains when type is `allowlist`. - - `x: number` + - `type: "allowlist"` - The x-coordinate where the double click occurred. + Allow outbound network access only to specified domains. Always `allowlist`. - - `y: number` + - `"allowlist"` - The y-coordinate where the double click occurred. + - `domain_secrets: optional array of ContainerNetworkPolicyDomainSecret` - - `Drag object { path, type, keys }` + Optional domain-scoped secrets for allowlisted domains. - A drag action. + - `domain: string` - - `path: array of object { x, y }` + The domain associated with the secret. - 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 secret to inject for the domain. - - `x: number` + - `value: string` - The x-coordinate. + The secret value to inject for the domain. - - `y: number` + - `type: "code_interpreter"` - The y-coordinate. + The type of the code interpreter tool. Always `code_interpreter`. - - `type: "drag"` + - `"code_interpreter"` - Specifies the event type. For a drag action, this property is always set to `drag`. + - `allowed_callers: optional array of "direct" or "programmatic"` - - `"drag"` + The tool invocation context(s). - - `keys: optional array of string` + - `"direct"` - The keys being held while dragging the mouse. + - `"programmatic"` - - `Keypress object { keys, type }` + - `ProgrammaticToolCalling object { type }` - A collection of keypresses the model would like to perform. + - `type: "programmatic_tool_calling"` - - `keys: array of string` + The type of the tool. Always `programmatic_tool_calling`. - The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. + - `"programmatic_tool_calling"` - - `type: "keypress"` + - `ImageGeneration object { type, action, background, 9 more }` - Specifies the event type. For a keypress action, this property is always set to `keypress`. + A tool that generates images using the GPT image models. - - `"keypress"` + - `type: "image_generation"` - - `Move object { type, x, y, keys }` + The type of the image generation tool. Always `image_generation`. - A mouse move action. + - `"image_generation"` - - `type: "move"` + - `action: optional "generate" or "edit" or "auto"` - Specifies the event type. For a move action, this property is always set to `move`. + Whether to generate a new image or edit an existing image. Default: `auto`. - - `"move"` + - `"generate"` - - `x: number` + - `"edit"` - The x-coordinate to move to. + - `"auto"` - - `y: number` + - `background: optional "transparent" or "opaque" or "auto"` - The y-coordinate to move to. + Background type for the generated image. One of `transparent`, + `opaque`, or `auto`. Default: `auto`. - - `keys: optional array of string` + - `"transparent"` - The keys being held while moving the mouse. + - `"opaque"` - - `Screenshot object { type }` + - `"auto"` - A screenshot action. + - `input_fidelity: optional "high" or "low"` - - `type: "screenshot"` + 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`. - Specifies the event type. For a screenshot action, this property is always set to `screenshot`. + - `"high"` - - `"screenshot"` + - `"low"` - - `Scroll object { scroll_x, scroll_y, type, 3 more }` + - `input_image_mask: optional object { file_id, image_url }` - A scroll action. + Optional mask for inpainting. Contains `image_url` + (string, optional) and `file_id` (string, optional). - - `scroll_x: number` + - `file_id: optional string` - The horizontal scroll distance. + File ID for the mask image. - - `scroll_y: number` + - `image_url: optional string` - The vertical scroll distance. + Base64-encoded mask image. - - `type: "scroll"` + - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` - Specifies the event type. For a scroll action, this property is always set to `scroll`. + The image generation model to use. Default: `gpt-image-1`. - - `"scroll"` + - `string` - - `x: number` + - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` - The x-coordinate where the scroll occurred. + The image generation model to use. Default: `gpt-image-1`. - - `y: number` + - `"gpt-image-1"` - The y-coordinate where the scroll occurred. + - `"gpt-image-1-mini"` - - `keys: optional array of string` + - `"gpt-image-1.5"` - The keys being held while scrolling. + - `moderation: optional "auto" or "low"` - - `Type object { text, type }` + Moderation level for the generated image. Default: `auto`. - An action to type in text. + - `"auto"` - - `text: string` + - `"low"` - The text to type. + - `output_compression: optional number` - - `type: "type"` + Compression level for the output image. Default: 100. - Specifies the event type. For a type action, this property is always set to `type`. + - `output_format: optional "png" or "webp" or "jpeg"` - - `"type"` + The output format of the generated image. One of `png`, `webp`, or + `jpeg`. Default: `png`. - - `Wait object { type }` + - `"png"` - A wait action. + - `"webp"` - - `type: "wait"` + - `"jpeg"` - Specifies the event type. For a wait action, this property is always set to `wait`. + - `partial_images: optional number` - - `"wait"` + Number of partial images to generate in streaming mode, from 0 (default value) to 3. - - `actions: optional ComputerActionList` + - `quality: optional "low" or "medium" or "high" or "auto"` - Flattened batched actions for `computer_use`. Each action includes an - `type` discriminator and action-specific fields. + The quality of the generated image. One of `low`, `medium`, `high`, + or `auto`. Default: `auto`. - - `Click object { button, type, x, 2 more }` + - `"low"` - A click action. + - `"medium"` - - `DoubleClick object { keys, type, x, y }` + - `"high"` - A double click action. + - `"auto"` - - `Drag object { path, type, keys }` + - `size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or "auto"` - A drag action. + 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`. - - `Keypress object { keys, type }` + - `string` - A collection of keypresses the model would like to perform. + - `"1024x1024" or "1024x1536" or "1536x1024" or "auto"` - - `Move object { type, x, y, keys }` + 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 mouse move action. + - `"1024x1024"` - - `Screenshot object { type }` + - `"1024x1536"` - A screenshot action. + - `"1536x1024"` - - `Scroll object { scroll_x, scroll_y, type, 3 more }` + - `"auto"` - A scroll action. + - `LocalShell object { type }` - - `Type object { text, type }` + A tool that allows the model to execute shell commands in a local environment. - An action to type in text. + - `type: "local_shell"` - - `Wait object { type }` + The type of the local shell tool. Always `local_shell`. - A wait action. + - `"local_shell"` - - `ComputerCallOutput object { call_id, output, type, 3 more }` + - `Shell object { type, allowed_callers, environment }` - The output of a computer tool call. + A tool that allows the model to execute shell commands. - - `call_id: string` + - `type: "shell"` - The ID of the computer tool call that produced the output. + The type of the shell tool. Always `shell`. - - `output: ResponseComputerToolCallOutputScreenshot` + - `"shell"` - A computer screenshot image used with the computer use tool. + - `allowed_callers: optional array of "direct" or "programmatic"` - - `type: "computer_screenshot"` + The tool invocation context(s). - Specifies the event type. For a computer screenshot, this property is - always set to `computer_screenshot`. + - `"direct"` - - `"computer_screenshot"` + - `"programmatic"` - - `file_id: optional string` + - `environment: optional ContainerAuto or LocalEnvironment or ContainerReference` - The identifier of an uploaded file that contains the screenshot. + - `ContainerAuto object { type, file_ids, memory_limit, 2 more }` - - `image_url: optional string` + - `type: "container_auto"` - The URL of the screenshot image. + Automatically creates a container for this request - - `type: "computer_call_output"` + - `"container_auto"` - The type of the computer tool call output. Always `computer_call_output`. + - `file_ids: optional array of string` - - `"computer_call_output"` + An optional list of uploaded files to make available to your code. - - `id: optional string` + - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` - The ID of the computer tool call output. + The memory limit for the container. - - `acknowledged_safety_checks: optional array of object { id, code, message }` + - `"1g"` - The safety checks reported by the API that have been acknowledged by the developer. + - `"4g"` - - `id: string` + - `"16g"` - The ID of the pending safety check. + - `"64g"` - - `code: optional string` + - `network_policy: optional ContainerNetworkPolicyDisabled or ContainerNetworkPolicyAllowlist` - The type of the pending safety check. + Network access policy for the container. - - `message: optional string` + - `ContainerNetworkPolicyDisabled object { type }` - Details about the pending safety check. + - `ContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` - - `status: optional "in_progress" or "completed" or "incomplete"` + - `skills: optional array of SkillReference or InlineSkill` - The status of the message input. One of `in_progress`, `completed`, or `incomplete`. Populated when input items are returned via API. + An optional list of skills referenced by id or inline data. - - `"in_progress"` + - `SkillReference object { skill_id, type, version }` - - `"completed"` + - `skill_id: string` - - `"incomplete"` + The ID of the referenced skill. - - `WebSearchCall object { id, action, status, type }` + - `type: "skill_reference"` - The results of a web search tool call. See the - [web search guide](/docs/guides/tools-web-search) for more information. + References a skill created with the /v1/skills endpoint. - - `id: string` + - `"skill_reference"` - The unique ID of the web search tool call. + - `version: optional string` - - `action: object { type, queries, query, sources } or object { type, url } or object { pattern, type, url }` + Optional skill version. Use a positive integer or 'latest'. Omit for default. - 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). + - `InlineSkill object { description, name, source, type }` - - `Search object { type, queries, query, sources }` + - `description: string` - Action type "search" - Performs a web search query. + The description of the skill. - - `type: "search"` + - `name: string` - The action type. + The name of the skill. - - `"search"` + - `source: InlineSkillSource` - - `queries: optional array of string` + Inline skill payload - The search queries. + - `data: string` - - `query: optional string` + Base64-encoded skill zip bundle. - The search query. + - `media_type: "application/zip"` - - `sources: optional array of object { type, url }` + The media type of the inline skill payload. Must be `application/zip`. - The sources used in the search. + - `"application/zip"` - - `type: "url"` + - `type: "base64"` - The type of source. Always `url`. + The type of the inline skill source. Must be `base64`. - - `"url"` + - `"base64"` - - `url: string` + - `type: "inline"` - The URL of the source. + Defines an inline skill for this request. - - `OpenPage object { type, url }` + - `"inline"` - Action type "open_page" - Opens a specific URL from search results. + - `LocalEnvironment object { type, skills }` - - `type: "open_page"` + - `type: "local"` - The action type. + Use a local computer environment. - - `"open_page"` + - `"local"` - - `url: optional string` + - `skills: optional array of LocalSkill` - The URL opened by the model. + An optional list of skills. - - `FindInPage object { pattern, type, url }` + - `description: string` - Action type "find_in_page": Searches for a pattern within a loaded page. + The description of the skill. - - `pattern: string` + - `name: string` - The pattern or text to search for within the page. + The name of the skill. - - `type: "find_in_page"` + - `path: string` - The action type. + The path to the directory containing the skill. - - `"find_in_page"` + - `ContainerReference object { container_id, type }` - - `url: string` + - `container_id: string` - The URL of the page searched for the pattern. + The ID of the referenced container. - - `status: "in_progress" or "searching" or "completed" or "failed"` + - `type: "container_reference"` - The status of the web search tool call. + References a container created with the /v1/containers endpoint - - `"in_progress"` + - `"container_reference"` - - `"searching"` + - `Custom object { name, type, allowed_callers, 3 more }` - - `"completed"` + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) - - `"failed"` + - `name: string` - - `type: "web_search_call"` + The name of the custom tool, used to identify it in tool calls. - The type of the web search tool call. Always `web_search_call`. + - `type: "custom"` - - `"web_search_call"` + The type of the custom tool. Always `custom`. - - `FunctionCall object { arguments, call_id, name, 5 more }` + - `"custom"` - A tool call to run a function. See the - [function calling guide](/docs/guides/function-calling) for more information. + - `allowed_callers: optional array of "direct" or "programmatic"` - - `arguments: string` + The tool invocation context(s). - A JSON string of the arguments to pass to the function. + - `"direct"` - - `call_id: string` + - `"programmatic"` - The unique ID of the function tool call generated by the model. + - `defer_loading: optional boolean` - - `name: string` + Whether this tool should be deferred and discovered via tool search. - The name of the function to run. + - `description: optional string` - - `type: "function_call"` + Optional description of the custom tool, used to provide more context. - The type of the function tool call. Always `function_call`. + - `format: optional CustomToolInputFormat` - - `"function_call"` + The input format for the custom tool. Default is unconstrained text. - - `id: optional string` + - `Text object { type }` - The unique ID of the function tool call. + Unconstrained free-form text. - - `caller: optional object { type } or object { caller_id, type }` + - `type: "text"` - The execution context that produced this tool call. + Unconstrained text format. Always `text`. - - `Direct object { type }` + - `"text"` - - `type: "direct"` + - `Grammar object { definition, syntax, type }` - - `"direct"` + A grammar defined by the user. - - `Program object { caller_id, type }` + - `definition: string` - - `caller_id: string` + The grammar definition. - The call ID of the program item that produced this tool call. + - `syntax: "lark" or "regex"` - - `type: "program"` + The syntax of the grammar definition. One of `lark` or `regex`. - - `"program"` + - `"lark"` - - `namespace: optional string` + - `"regex"` - The namespace of the function to run. + - `type: "grammar"` - - `status: optional "in_progress" or "completed" or "incomplete"` + Grammar format. Always `grammar`. - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `"grammar"` - - `"in_progress"` + - `Namespace object { description, name, tools, type }` - - `"completed"` + Groups function/custom tools under a shared namespace. - - `"incomplete"` + - `description: string` - - `FunctionCallOutput object { call_id, output, type, 3 more }` + A description of the namespace shown to the model. - The output of a function tool call. + - `name: string` - - `call_id: string` + The namespace name used in tool calls (for example, `crm`). - The unique ID of the function tool call generated by the model. + - `tools: array of object { name, type, allowed_callers, 5 more } or object { name, type, allowed_callers, 3 more }` - - `output: string or array of ResponseInputTextContent or ResponseInputImageContent or ResponseInputFileContent` + The function/custom tools available inside this namespace. - Text, image, or file output of the function tool call. + - `Function object { name, type, allowed_callers, 5 more }` - - `string` + - `name: string` - A JSON string of the output of the function tool call. + - `type: "function"` - - `array of ResponseInputTextContent or ResponseInputImageContent or ResponseInputFileContent` + - `"function"` - An array of content outputs (text, image, file) for the function tool call. + - `allowed_callers: optional array of "direct" or "programmatic"` - - `ResponseInputTextContent object { text, type, prompt_cache_breakpoint }` + The tool invocation context(s). - A text input to the model. + - `"direct"` - - `text: string` + - `"programmatic"` - The text input to the model. + - `defer_loading: optional boolean` - - `type: "input_text"` + Whether this function should be deferred and discovered via tool search. - The type of the input item. Always `input_text`. + - `description: optional string` - - `"input_text"` + - `output_schema: optional map[unknown]` - - `prompt_cache_breakpoint: optional object { mode }` + A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + - `parameters: optional unknown` - - `mode: "explicit"` + - `strict: optional boolean` - The breakpoint mode. Always `explicit`. + Whether to enforce strict parameter validation. If omitted, Responses attempts to use strict validation when the schema is compatible, and falls back to non-strict validation otherwise. - - `"explicit"` + - `Custom object { name, type, allowed_callers, 3 more }` - - `ResponseInputImageContent object { type, detail, file_id, 2 more }` + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) - An image input to the model. Learn about [image inputs](/docs/guides/vision) + - `name: string` - - `type: "input_image"` + The name of the custom tool, used to identify it in tool calls. - The type of the input item. Always `input_image`. + - `type: "custom"` - - `"input_image"` + The type of the custom tool. Always `custom`. - - `detail: optional "low" or "high" or "auto" or "original"` + - `"custom"` - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + - `allowed_callers: optional array of "direct" or "programmatic"` - - `"low"` + The tool invocation context(s). - - `"high"` + - `"direct"` - - `"auto"` + - `"programmatic"` - - `"original"` + - `defer_loading: optional boolean` - - `file_id: optional string` + Whether this tool should be deferred and discovered via tool search. - The ID of the file to be sent to the model. + - `description: optional string` - - `image_url: optional string` + Optional description of the custom tool, used to provide more context. - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + - `format: optional CustomToolInputFormat` - - `prompt_cache_breakpoint: optional object { mode }` + The input format for the custom tool. Default is unconstrained text. - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + - `type: "namespace"` - - `mode: "explicit"` + The type of the tool. Always `namespace`. - The breakpoint mode. Always `explicit`. + - `"namespace"` - - `"explicit"` + - `ToolSearch object { type, description, execution, parameters }` - - `ResponseInputFileContent object { type, detail, file_data, 4 more }` + Hosted or BYOT tool search configuration for deferred tools. - A file input to the model. + - `type: "tool_search"` - - `type: "input_file"` + The type of the tool. Always `tool_search`. - The type of the input item. Always `input_file`. + - `"tool_search"` - - `"input_file"` + - `description: optional string` - - `detail: optional "auto" or "low" or "high"` + Description shown to the model for a client-executed tool search tool. - The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. + - `execution: optional "server" or "client"` - - `"auto"` + Whether tool search is executed by the server or by the client. - - `"low"` + - `"server"` - - `"high"` + - `"client"` - - `file_data: optional string` + - `parameters: optional unknown` - The base64-encoded data of the file to be sent to the model. + 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). - - `file_url: optional string` + - `type: "web_search_preview" or "web_search_preview_2025_03_11"` - The URL of the file to be sent to the model. + The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. - - `filename: optional string` + - `"web_search_preview"` - The name of the file to be sent to the model. + - `"web_search_preview_2025_03_11"` - - `prompt_cache_breakpoint: optional object { mode }` + - `search_content_types: optional array of "text" or "image"` - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + - `"text"` - - `mode: "explicit"` + - `"image"` - The breakpoint mode. Always `explicit`. + - `search_context_size: optional "low" or "medium" or "high"` - - `"explicit"` + 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: "function_call_output"` + - `"low"` - The type of the function tool call output. Always `function_call_output`. + - `"medium"` - - `"function_call_output"` + - `"high"` - - `id: optional string` + - `user_location: optional object { type, city, country, 2 more }` - The unique ID of the function tool call output. Populated when this item is returned via API. + The user's location. - - `caller: optional object { type } or object { caller_id, type }` + - `type: "approximate"` - The execution context that produced this tool call. + The type of location approximation. Always `approximate`. - - `Direct object { type }` + - `"approximate"` - - `type: "direct"` + - `city: optional string` - The caller type. Always `direct`. + Free text input for the city of the user, e.g. `San Francisco`. - - `"direct"` + - `country: optional string` - - `Program object { caller_id, type }` + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - - `caller_id: string` + - `region: optional string` - The call ID of the program item that produced this tool call. + Free text input for the region of the user, e.g. `California`. - - `type: "program"` + - `timezone: optional string` - The caller type. Always `program`. + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - - `"program"` + - `ApplyPatch object { type, allowed_callers }` - - `status: optional "in_progress" or "completed" or "incomplete"` + Allows the assistant to create, delete, or update files using unified diffs. - The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. + - `type: "apply_patch"` - - `"in_progress"` + The type of the tool. Always `apply_patch`. - - `"completed"` + - `"apply_patch"` - - `"incomplete"` + - `allowed_callers: optional array of "direct" or "programmatic"` - - `ToolSearchCall object { arguments, type, id, 3 more }` + The tool invocation context(s). - - `arguments: unknown` + - `"direct"` - The arguments supplied to the tool search call. + - `"programmatic"` - - `type: "tool_search_call"` + - `type: "tool_search_output"` - The item type. Always `tool_search_call`. + The item type. Always `tool_search_output`. - - `"tool_search_call"` + - `"tool_search_output"` - `id: optional string` - The unique ID of this tool search call. + The unique ID of this tool search output. - `call_id: optional string` @@ -35679,7 +35851,7 @@ Learn when and how to compact long-running conversations in the [conversation st - `status: optional "in_progress" or "completed" or "incomplete"` - The status of the tool search call. + The status of the tool search output. - `"in_progress"` @@ -35687,11 +35859,17 @@ Learn when and how to compact long-running conversations in the [conversation st - `"incomplete"` - - `ToolSearchOutput object { tools, type, id, 3 more }` + - `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, 5 more } or object { type, vector_store_ids, filters, 2 more } or object { type } or 13 more` - The loaded tool definitions returned by the tool search output. + A list of additional tools made available at this item. - `Function object { name, parameters, strict, 5 more }` @@ -35757,77 +35935,10 @@ Learn when and how to compact long-running conversations in the [conversation st 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. @@ -36163,40 +36274,8 @@ Learn when and how to compact long-running conversations in the [conversation st - `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`. @@ -36377,128 +36456,10 @@ Learn when and how to compact long-running conversations in the [conversation st - `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, allowed_callers, 3 more }` A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) @@ -36533,38 +36494,6 @@ Learn when and how to compact long-running conversations in the [conversation st 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. @@ -36735,1183 +36664,1294 @@ Learn when and how to compact long-running conversations in the [conversation st - `ApplyPatch object { type, allowed_callers }` - Allows the assistant to create, delete, or update files using unified diffs. + 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"` + + - `allowed_callers: optional array of "direct" or "programmatic"` + + The tool invocation context(s). + + - `"direct"` + + - `"programmatic"` + + - `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. This is populated by default + for reasoning items returned by `POST /v1/responses` and WebSocket + `response.create` requests. + + - `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`. - - `type: "apply_patch"` + - `"image_generation_call"` - The type of the tool. Always `apply_patch`. + - `CodeInterpreterCall object { id, code, container_id, 3 more }` - - `"apply_patch"` + A tool call to run code. - - `allowed_callers: optional array of "direct" or "programmatic"` + - `id: string` - The tool invocation context(s). + The unique ID of the code interpreter tool call. - - `"direct"` + - `code: string` - - `"programmatic"` + The code to run, or null if not available. - - `type: "tool_search_output"` + - `container_id: string` - The item type. Always `tool_search_output`. + The ID of the container used to run the code. - - `"tool_search_output"` + - `outputs: array of object { logs, type } or object { type, url }` - - `id: optional string` + The outputs generated by the code interpreter, such as logs or images. + Can be null if no outputs are available. - The unique ID of this tool search output. + - `Logs object { logs, type }` - - `call_id: optional string` + The logs output from the code interpreter. - The unique ID of the tool search call generated by the model. + - `logs: string` - - `execution: optional "server" or "client"` + The logs output from the code interpreter. - Whether tool search was executed by the server or by the client. + - `type: "logs"` - - `"server"` + The type of the output. Always `logs`. - - `"client"` + - `"logs"` - - `status: optional "in_progress" or "completed" or "incomplete"` + - `Image object { type, url }` - The status of the tool search output. + The image output from the code interpreter. - - `"in_progress"` + - `type: "image"` - - `"completed"` + The type of the output. Always `image`. - - `"incomplete"` + - `"image"` - - `AdditionalTools object { role, tools, type, id }` + - `url: string` - - `role: "developer"` + The URL of the image output from the code interpreter. - The role that provided the additional tools. Only `developer` is supported. + - `status: "in_progress" or "completed" or "incomplete" or 2 more` - - `"developer"` + The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. - - `tools: array of object { name, parameters, strict, 5 more } or object { type, vector_store_ids, filters, 2 more } or object { type } or 13 more` + - `"in_progress"` - A list of additional tools made available at this item. + - `"completed"` - - `Function object { name, parameters, strict, 5 more }` + - `"incomplete"` - 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). + - `"interpreting"` - - `name: string` + - `"failed"` - The name of the function to call. + - `type: "code_interpreter_call"` - - `parameters: map[unknown]` + The type of the code interpreter tool call. Always `code_interpreter_call`. - A JSON schema object describing the parameters of the function. + - `"code_interpreter_call"` - - `strict: boolean` + - `LocalShellCall object { id, action, call_id, 2 more }` - Whether strict parameter validation is enforced for this function tool. + A tool call to run a command on the local shell. - - `type: "function"` + - `id: string` - The type of the function tool. Always `function`. + The unique ID of the local shell call. - - `"function"` + - `action: object { command, env, type, 3 more }` - - `allowed_callers: optional array of "direct" or "programmatic"` + Execute a shell command on the server. - The tool invocation context(s). + - `command: array of string` - - `"direct"` + The command to run. - - `"programmatic"` + - `env: map[string]` - - `defer_loading: optional boolean` + Environment variables to set for the command. - Whether this function is deferred and loaded via tool search. + - `type: "exec"` - - `description: optional string` + The type of the local shell action. Always `exec`. - A description of the function. Used by the model to determine whether or not to call the function. + - `"exec"` - - `output_schema: optional map[unknown]` + - `timeout_ms: optional number` - A JSON schema object describing the JSON value encoded in string outputs for this function. + Optional timeout in milliseconds for the command. - - `FileSearch object { type, vector_store_ids, filters, 2 more }` + - `user: 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 user to run the command as. - - `type: "file_search"` + - `working_directory: optional string` - The type of the file search tool. Always `file_search`. + Optional working directory to run the command in. - - `"file_search"` + - `call_id: string` - - `vector_store_ids: array of string` + The unique ID of the local shell tool call generated by the model. - The IDs of the vector stores to search. + - `status: "in_progress" or "completed" or "incomplete"` - - `filters: optional ComparisonFilter or CompoundFilter` + The status of the local shell call. - 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: "local_shell_call"` - Combine multiple filters using `and` or `or`. + The type of the local shell call. Always `local_shell_call`. - - `max_num_results: optional number` + - `"local_shell_call"` - The maximum number of results to return. This number should be between 1 and 50 inclusive. + - `LocalShellCallOutput object { id, output, type, status }` - - `ranking_options: optional object { hybrid_search, ranker, score_threshold }` + The output of a local shell tool call. - Ranking options for search. + - `id: string` - - `hybrid_search: optional object { embedding_weight, text_weight }` + The unique ID of the local shell tool call generated by the model. - Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. + - `output: string` - - `embedding_weight: number` + A JSON string of the output of the local shell tool call. - The weight of the embedding in the reciprocal ranking fusion. + - `type: "local_shell_call_output"` - - `text_weight: number` + The type of the local shell tool call output. Always `local_shell_call_output`. - The weight of the text in the reciprocal ranking fusion. + - `"local_shell_call_output"` - - `ranker: optional "auto" or "default-2024-11-15"` + - `status: optional "in_progress" or "completed" or "incomplete"` - The ranker to use for the file search. + The status of the item. One of `in_progress`, `completed`, or `incomplete`. - - `"auto"` + - `"in_progress"` - - `"default-2024-11-15"` + - `"completed"` - - `score_threshold: optional number` + - `"incomplete"` - 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. + - `ShellCall object { action, call_id, type, 4 more }` - - `Computer object { type }` + A tool representing a request to execute one or more shell commands. - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `action: object { commands, max_output_length, timeout_ms }` - - `type: "computer"` + The shell commands and limits that describe how to run the tool call. - The type of the computer tool. Always `computer`. + - `commands: array of string` - - `"computer"` + Ordered shell commands for the execution environment to run. - - `ComputerUsePreview object { display_height, display_width, environment, type }` + - `max_output_length: optional number` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + Maximum number of UTF-8 characters to capture from combined stdout and stderr output. - - `display_height: number` + - `timeout_ms: optional number` - The height of the computer display. + Maximum wall-clock time in milliseconds to allow the shell commands to run. - - `display_width: number` + - `call_id: string` - The width of the computer display. + The unique ID of the shell tool call generated by the model. - - `environment: "windows" or "mac" or "linux" or 2 more` + - `type: "shell_call"` - The type of computer environment to control. + The type of the item. Always `shell_call`. - - `"windows"` + - `"shell_call"` - - `"mac"` + - `id: optional string` - - `"linux"` + The unique ID of the shell tool call. Populated when this item is returned via API. - - `"ubuntu"` + - `caller: optional object { type } or object { caller_id, type }` - - `"browser"` + The execution context that produced this tool call. - - `type: "computer_use_preview"` + - `Direct object { type }` - The type of the computer use tool. Always `computer_use_preview`. + - `type: "direct"` - - `"computer_use_preview"` + The caller type. Always `direct`. - - `WebSearch object { type, filters, search_context_size, user_location }` + - `"direct"` - Search the Internet for sources related to the prompt. Learn more about the - [web search tool](/docs/guides/tools-web-search). + - `Program object { caller_id, type }` - - `type: "web_search" or "web_search_2025_08_26"` + - `caller_id: string` - The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. + The call ID of the program item that produced this tool call. - - `"web_search"` + - `type: "program"` - - `"web_search_2025_08_26"` + The caller type. Always `program`. - - `filters: optional object { allowed_domains }` + - `"program"` - Filters for the search. + - `environment: optional LocalEnvironment or ContainerReference` - - `allowed_domains: optional array of string` + The environment to execute the shell commands in. - Allowed domains for the search. If not provided, all domains are allowed. - Subdomains of the provided domains are allowed as well. + - `LocalEnvironment object { type, skills }` - Example: `["pubmed.ncbi.nlm.nih.gov"]` + - `ContainerReference object { container_id, type }` - - `search_context_size: optional "low" or "medium" or "high"` + - `status: optional "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. One of `in_progress`, `completed`, or `incomplete`. - - `"low"` + - `"in_progress"` - - `"medium"` + - `"completed"` - - `"high"` + - `"incomplete"` - - `user_location: optional object { city, country, region, 2 more }` + - `ShellCallOutput object { call_id, output, type, 4 more }` - The approximate location of the user. + The streamed output items emitted by a shell tool call. - - `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` + - `output: array of ResponseFunctionShellCallOutputContent` - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + Captured chunks of stdout and stderr output, along with their associated outcomes. - - `region: optional string` + - `outcome: object { type } or object { exit_code, type }` - Free text input for the region of the user, e.g. `California`. + The exit or timeout outcome associated with this shell call. - - `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. - - `type: optional "approximate"` + - `type: "timeout"` - The type of location approximation. Always `approximate`. + The outcome type. Always `timeout`. - - `"approximate"` + - `"timeout"` - - `Mcp object { server_label, type, allowed_callers, 9 more }` + - `Exit object { exit_code, type }` - Give the model access to additional tools via remote Model Context Protocol - (MCP) servers. [Learn more about MCP](/docs/guides/tools-remote-mcp). + Indicates that the shell commands finished and returned an exit code. - - `server_label: string` + - `exit_code: number` - A label for this MCP server, used to identify it in tool calls. + The exit code returned by the shell process. - - `type: "mcp"` + - `type: "exit"` - The type of the MCP tool. Always `mcp`. + The outcome type. Always `exit`. - - `"mcp"` + - `"exit"` - - `allowed_callers: optional array of "direct" or "programmatic"` + - `stderr: string` - The tool invocation context(s). + Captured stderr output for the shell call. - - `"direct"` + - `stdout: string` - - `"programmatic"` + Captured stdout output for the shell call. - - `allowed_tools: optional array of string or object { read_only, tool_names }` + - `type: "shell_call_output"` - List of allowed tool names or a filter object. + The type of the item. Always `shell_call_output`. - - `McpAllowedTools = array of string` + - `"shell_call_output"` - A string array of allowed tool names + - `id: optional string` - - `McpToolFilter object { read_only, tool_names }` + The unique ID of the shell tool call output. Populated when this item is returned via API. - A filter object to specify which tools are allowed. + - `caller: optional object { type } or object { caller_id, type }` - - `read_only: optional boolean` + The execution context that produced 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. + - `Direct object { type }` - - `tool_names: optional array of string` + - `type: "direct"` - List of allowed tool names. + The caller type. Always `direct`. - - `authorization: optional string` + - `"direct"` - 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. + - `Program object { caller_id, type }` - - `connector_id: optional "connector_dropbox" or "connector_gmail" or "connector_googlecalendar" or 5 more` + - `caller_id: string` - Identifier for service connectors, like those available in ChatGPT. One of - `server_url`, `connector_id`, or `tunnel_id` must be provided. Learn more - about service connectors [here](/docs/guides/tools-remote-mcp#connectors). + The call ID of the program item that produced this tool call. - Currently supported `connector_id` values are: + - `type: "program"` - - 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 caller type. Always `program`. - - `"connector_dropbox"` + - `"program"` - - `"connector_gmail"` + - `max_output_length: optional number` - - `"connector_googlecalendar"` + The maximum number of UTF-8 characters captured for this shell call's combined output. - - `"connector_googledrive"` + - `status: optional "in_progress" or "completed" or "incomplete"` - - `"connector_microsoftteams"` + The status of the shell call output. - - `"connector_outlookcalendar"` + - `"in_progress"` - - `"connector_outlookemail"` + - `"completed"` - - `"connector_sharepoint"` + - `"incomplete"` - - `defer_loading: optional boolean` + - `ApplyPatchCall object { call_id, operation, status, 3 more }` - Whether this MCP tool is deferred and discovered via tool search. + A tool call representing a request to create, delete, or update files using diff patches. - - `headers: optional map[string]` + - `call_id: string` - Optional HTTP headers to send to the MCP server. Use for authentication - or other purposes. + The unique ID of the apply patch tool call generated by the model. - - `require_approval: optional object { always, never } or "always" or "never"` + - `operation: object { diff, path, type } or object { path, type } or object { diff, path, type }` - Specify which of the MCP server's tools require approval. + The specific create, delete, or update instruction for the apply_patch tool call. - - `McpToolApprovalFilter object { always, never }` + - `CreateFile object { diff, path, 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. + Instruction for creating a new file via the apply_patch tool. - - `always: optional object { read_only, tool_names }` + - `diff: string` - A filter object to specify which tools are allowed. + Unified diff content to apply when creating the file. - - `read_only: optional boolean` + - `path: 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. + Path of the file to create relative to the workspace root. - - `tool_names: optional array of string` + - `type: "create_file"` - List of allowed tool names. + The operation type. Always `create_file`. - - `never: optional object { read_only, tool_names }` + - `"create_file"` - A filter object to specify which tools are allowed. + - `DeleteFile object { path, type }` - - `read_only: optional boolean` + Instruction for deleting an existing file via the apply_patch 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. + - `path: string` - - `tool_names: optional array of string` + Path of the file to delete relative to the workspace root. - List of allowed tool names. + - `type: "delete_file"` - - `McpToolApprovalSetting = "always" or "never"` + The operation type. Always `delete_file`. - 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. + - `"delete_file"` - - `"always"` + - `UpdateFile object { diff, path, type }` - - `"never"` + Instruction for updating an existing file via the apply_patch tool. - - `server_description: optional string` + - `diff: string` - Optional description of the MCP server, used to provide more context. + Unified diff content to apply to the existing file. - - `server_url: optional string` + - `path: string` - The URL for the MCP server. One of `server_url`, `connector_id`, or - `tunnel_id` must be provided. + Path of the file to update relative to the workspace root. - - `tunnel_id: optional string` + - `type: "update_file"` - The Secure MCP Tunnel ID to use instead of a direct server URL. One of - `server_url`, `connector_id`, or `tunnel_id` must be provided. + The operation type. Always `update_file`. - - `CodeInterpreter object { container, type, allowed_callers }` + - `"update_file"` - A tool that runs Python code to help generate a response to a prompt. + - `status: "in_progress" or "completed"` - - `container: string or object { type, file_ids, memory_limit, network_policy }` + The status of the apply patch tool call. One of `in_progress` or `completed`. - 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. + - `type: "apply_patch_call"` - - `CodeInterpreterToolAuto object { type, file_ids, memory_limit, network_policy }` + The type of the item. Always `apply_patch_call`. - Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. + - `"apply_patch_call"` - - `type: "auto"` + - `id: optional string` - Always `auto`. + The unique ID of the apply patch tool call. Populated when this item is returned via API. - - `"auto"` + - `caller: optional object { type } or object { caller_id, type }` - - `file_ids: optional array of string` + The execution context that produced this tool call. - An optional list of uploaded files to make available to your code. + - `Direct object { type }` - - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` + - `type: "direct"` - The memory limit for the code interpreter container. + The caller type. Always `direct`. - - `"1g"` + - `"direct"` - - `"4g"` + - `Program object { caller_id, type }` - - `"16g"` + - `caller_id: string` - - `"64g"` + The call ID of the program item that produced this tool call. - - `network_policy: optional ContainerNetworkPolicyDisabled or ContainerNetworkPolicyAllowlist` + - `type: "program"` - Network access policy for the container. + The caller type. Always `program`. - - `ContainerNetworkPolicyDisabled object { type }` + - `"program"` - - `ContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` + - `ApplyPatchCallOutput object { call_id, status, type, 3 more }` - - `type: "code_interpreter"` + The streamed output emitted by an apply patch tool call. - The type of the code interpreter tool. Always `code_interpreter`. + - `call_id: string` - - `"code_interpreter"` + The unique ID of the apply patch tool call generated by the model. - - `allowed_callers: optional array of "direct" or "programmatic"` + - `status: "completed" or "failed"` - The tool invocation context(s). + The status of the apply patch tool call output. One of `completed` or `failed`. - - `"direct"` + - `"completed"` - - `"programmatic"` + - `"failed"` - - `ProgrammaticToolCalling object { type }` + - `type: "apply_patch_call_output"` - - `type: "programmatic_tool_calling"` + The type of the item. Always `apply_patch_call_output`. - The type of the tool. Always `programmatic_tool_calling`. + - `"apply_patch_call_output"` - - `"programmatic_tool_calling"` + - `id: optional string` - - `ImageGeneration object { type, action, background, 9 more }` + The unique ID of the apply patch tool call output. Populated when this item is returned via API. - A tool that generates images using the GPT image models. + - `caller: optional object { type } or object { caller_id, type }` - - `type: "image_generation"` + The execution context that produced this tool call. - The type of the image generation tool. Always `image_generation`. + - `Direct object { type }` - - `"image_generation"` + - `type: "direct"` - - `action: optional "generate" or "edit" or "auto"` + The caller type. Always `direct`. - Whether to generate a new image or edit an existing image. Default: `auto`. + - `"direct"` - - `"generate"` + - `Program object { caller_id, type }` - - `"edit"` + - `caller_id: string` - - `"auto"` + The call ID of the program item that produced this tool call. - - `background: optional "transparent" or "opaque" or "auto"` + - `type: "program"` - Background type for the generated image. One of `transparent`, - `opaque`, or `auto`. Default: `auto`. + The caller type. Always `program`. - - `"transparent"` + - `"program"` - - `"opaque"` + - `output: optional string` - - `"auto"` + Optional human-readable log text from the apply patch tool (e.g., patch results or errors). - - `input_fidelity: optional "high" or "low"` + - `McpListTools object { id, server_label, tools, 2 more }` - 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`. + A list of tools available on an MCP server. - - `"high"` + - `id: string` - - `"low"` + The unique ID of the list. - - `input_image_mask: optional object { file_id, image_url }` + - `server_label: string` - Optional mask for inpainting. Contains `image_url` - (string, optional) and `file_id` (string, optional). + The label of the MCP server. - - `file_id: optional string` + - `tools: array of object { input_schema, name, annotations, description }` - File ID for the mask image. + The tools available on the server. - - `image_url: optional string` + - `input_schema: unknown` - Base64-encoded mask image. + The JSON schema describing the tool's input. - - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` + - `name: string` - The image generation model to use. Default: `gpt-image-1`. + The name of the tool. - - `string` + - `annotations: optional unknown` - - `"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` - - `"gpt-image-1"` + The description of the tool. - - `"gpt-image-1-mini"` + - `type: "mcp_list_tools"` - - `"gpt-image-1.5"` + The type of the item. Always `mcp_list_tools`. - - `moderation: optional "auto" or "low"` + - `"mcp_list_tools"` - Moderation level for the generated image. Default: `auto`. + - `error: optional string` - - `"auto"` + Error message if the server could not list tools. - - `"low"` + - `McpApprovalRequest object { id, arguments, name, 2 more }` - - `output_compression: optional number` + A request for human approval of a tool invocation. - Compression level for the output image. Default: 100. + - `id: string` - - `output_format: optional "png" or "webp" or "jpeg"` + The unique ID of the approval request. - The output format of the generated image. One of `png`, `webp`, or - `jpeg`. Default: `png`. + - `arguments: string` - - `"png"` + A JSON string of arguments for the tool. - - `"webp"` + - `name: string` - - `"jpeg"` + The name of the tool to run. - - `partial_images: optional number` + - `server_label: string` - Number of partial images to generate in streaming mode, from 0 (default value) to 3. + The label of the MCP server making the request. - - `quality: optional "low" or "medium" or "high" or "auto"` + - `type: "mcp_approval_request"` - The quality of the generated image. One of `low`, `medium`, `high`, - or `auto`. Default: `auto`. + The type of the item. Always `mcp_approval_request`. - - `"low"` + - `"mcp_approval_request"` - - `"medium"` + - `McpApprovalResponse object { approval_request_id, approve, type, 2 more }` - - `"high"` + A response to an MCP approval request. - - `"auto"` + - `approval_request_id: string` - - `size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or "auto"` + The ID of the approval request being answered. - 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`. + - `approve: boolean` - - `string` + Whether the request was approved. - - `"1024x1024" or "1024x1536" or "1536x1024" or "auto"` + - `type: "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`. + The type of the item. Always `mcp_approval_response`. - - `"1024x1024"` + - `"mcp_approval_response"` - - `"1024x1536"` + - `id: optional string` - - `"1536x1024"` + The unique ID of the approval response - - `"auto"` + - `reason: optional string` - - `LocalShell object { type }` + Optional reason for the decision. - A tool that allows the model to execute shell commands in a local environment. + - `McpCall object { id, arguments, name, 6 more }` - - `type: "local_shell"` + An invocation of a tool on an MCP server. - The type of the local shell tool. Always `local_shell`. + - `id: string` - - `"local_shell"` + The unique ID of the tool call. - - `Shell object { type, allowed_callers, environment }` + - `arguments: string` - A tool that allows the model to execute shell commands. + A JSON string of the arguments passed to the tool. - - `type: "shell"` + - `name: string` - The type of the shell tool. Always `shell`. + The name of the tool that was run. - - `"shell"` + - `server_label: string` - - `allowed_callers: optional array of "direct" or "programmatic"` + The label of the MCP server running the tool. - The tool invocation context(s). + - `type: "mcp_call"` - - `"direct"` + The type of the item. Always `mcp_call`. - - `"programmatic"` + - `"mcp_call"` - - `environment: optional ContainerAuto or LocalEnvironment or ContainerReference` + - `approval_request_id: optional string` - - `ContainerAuto object { type, file_ids, memory_limit, 2 more }` + 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. - - `LocalEnvironment object { type, skills }` + - `error: optional string` - - `ContainerReference object { container_id, type }` + The error from the tool call, if any. - - `Custom object { name, type, allowed_callers, 3 more }` + - `output: optional string` - A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) + The output from the tool call. - - `name: string` + - `status: optional "in_progress" or "completed" or "incomplete" or 2 more` - The name of the custom tool, used to identify it in tool calls. + The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. - - `type: "custom"` + - `"in_progress"` - The type of the custom tool. Always `custom`. + - `"completed"` - - `"custom"` + - `"incomplete"` - - `allowed_callers: optional array of "direct" or "programmatic"` + - `"calling"` - The tool invocation context(s). + - `"failed"` - - `"direct"` + - `CustomToolCallOutput object { call_id, output, type, 2 more }` - - `"programmatic"` + The output of a custom tool call from your code, being sent back to the model. - - `defer_loading: optional boolean` + - `call_id: string` - Whether this tool should be deferred and discovered via tool search. + The call ID, used to map this custom tool call output to a custom tool call. - - `description: optional string` + - `output: string or array of ResponseInputText or ResponseInputImage or ResponseInputFile` - Optional description of the custom tool, used to provide more context. + The output from the custom tool call generated by your code. + Can be a string or an list of output content. - - `format: optional CustomToolInputFormat` + - `StringOutput = string` - The input format for the custom tool. Default is unconstrained text. + A string of the output of the custom tool call. - - `Namespace object { description, name, tools, type }` + - `OutputContentList = array of ResponseInputText or ResponseInputImage or ResponseInputFile` - Groups function/custom tools under a shared namespace. + Text, image, or file output of the custom tool call. - - `description: string` + - `ResponseInputText object { text, type, prompt_cache_breakpoint }` - A description of the namespace shown to the model. + A text input to the model. - - `name: string` + - `ResponseInputImage object { detail, type, file_id, 2 more }` - The namespace name used in tool calls (for example, `crm`). + An image input to the model. Learn about [image inputs](/docs/guides/vision). - - `tools: array of object { name, type, allowed_callers, 5 more } or object { name, type, allowed_callers, 3 more }` + - `ResponseInputFile object { type, detail, file_data, 4 more }` - The function/custom tools available inside this namespace. + A file input to the model. - - `Function object { name, type, allowed_callers, 5 more }` + - `type: "custom_tool_call_output"` - - `name: string` + The type of the custom tool call output. Always `custom_tool_call_output`. - - `type: "function"` + - `"custom_tool_call_output"` - - `"function"` + - `id: optional string` - - `allowed_callers: optional array of "direct" or "programmatic"` + The unique ID of the custom tool call output in the OpenAI platform. - The tool invocation context(s). + - `caller: optional object { type } or object { caller_id, type }` - - `"direct"` + The execution context that produced this tool call. - - `"programmatic"` + - `Direct object { type }` - - `defer_loading: optional boolean` + - `type: "direct"` - Whether this function should be deferred and discovered via tool search. + The caller type. Always `direct`. - - `description: optional string` + - `"direct"` - - `output_schema: optional map[unknown]` + - `Program object { caller_id, type }` - A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. + - `caller_id: string` - - `parameters: optional unknown` + The call ID of the program item that produced this tool call. - - `strict: optional boolean` + - `type: "program"` - Whether to enforce strict parameter validation. If omitted, Responses attempts to use strict validation when the schema is compatible, and falls back to non-strict validation otherwise. + The caller type. Always `program`. - - `Custom object { name, type, allowed_callers, 3 more }` + - `"program"` - A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) + - `CustomToolCall object { call_id, input, name, 4 more }` - - `name: string` + A call to a custom tool created by the model. - The name of the custom tool, used to identify it in tool calls. + - `call_id: string` - - `type: "custom"` + An identifier used to map this custom tool call to a tool call output. - The type of the custom tool. Always `custom`. + - `input: string` - - `"custom"` + The input for the custom tool call generated by the model. - - `allowed_callers: optional array of "direct" or "programmatic"` + - `name: string` - The tool invocation context(s). + The name of the custom tool being called. - - `"direct"` + - `type: "custom_tool_call"` - - `"programmatic"` + The type of the custom tool call. Always `custom_tool_call`. - - `defer_loading: optional boolean` + - `"custom_tool_call"` - Whether this tool should be deferred and discovered via tool search. + - `id: optional string` - - `description: optional string` + The unique ID of the custom tool call in the OpenAI platform. - Optional description of the custom tool, used to provide more context. + - `caller: optional object { type } or object { caller_id, type }` - - `format: optional CustomToolInputFormat` + The execution context that produced this tool call. - The input format for the custom tool. Default is unconstrained text. + - `Direct object { type }` - - `type: "namespace"` + - `type: "direct"` - The type of the tool. Always `namespace`. + - `"direct"` - - `"namespace"` + - `Program object { caller_id, type }` - - `ToolSearch object { type, description, execution, parameters }` + - `caller_id: string` - Hosted or BYOT tool search configuration for deferred tools. + The call ID of the program item that produced this tool call. - - `type: "tool_search"` + - `type: "program"` - The type of the tool. Always `tool_search`. + - `"program"` - - `"tool_search"` + - `namespace: optional string` - - `description: optional string` + The namespace of the custom tool being called. - Description shown to the model for a client-executed tool search tool. + - `CompactionTrigger object { type }` - - `execution: optional "server" or "client"` + Compacts the current context. Must be the final input item. - Whether tool search is executed by the server or by the client. + - `type: "compaction_trigger"` - - `"server"` + The type of the item. Always `compaction_trigger`. - - `"client"` + - `"compaction_trigger"` - - `parameters: optional unknown` + - `ItemReference object { id, type }` - Parameter schema for a client-executed tool search tool. + An internal identifier for an item to reference. - - `WebSearchPreview object { type, search_content_types, search_context_size, user_location }` + - `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 ID of the item to reference. - - `type: "web_search_preview" or "web_search_preview_2025_03_11"` + - `type: optional "item_reference"` - The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. + The type of item to reference. Always `item_reference`. - - `"web_search_preview"` + - `"item_reference"` - - `"web_search_preview_2025_03_11"` + - `Program object { id, call_id, code, 2 more }` - - `search_content_types: optional array of "text" or "image"` + - `id: string` - - `"text"` + The unique ID of this program item. - - `"image"` + - `call_id: string` - - `search_context_size: optional "low" or "medium" or "high"` + The stable call ID of the program 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. + - `code: string` - - `"low"` + The JavaScript source executed by programmatic tool calling. - - `"medium"` + - `fingerprint: string` - - `"high"` + Opaque program replay fingerprint that must be round-tripped. - - `user_location: optional object { type, city, country, 2 more }` + - `type: "program"` - The user's location. + The item type. Always `program`. - - `type: "approximate"` + - `"program"` - The type of location approximation. Always `approximate`. + - `ProgramOutput object { id, call_id, result, 2 more }` - - `"approximate"` + - `id: string` - - `city: optional string` + The unique ID of this program output item. - Free text input for the city of the user, e.g. `San Francisco`. + - `call_id: string` - - `country: optional string` + The call ID of the program item. - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + - `result: string` - - `region: optional string` + The result produced by the program item. - Free text input for the region of the user, e.g. `California`. + - `status: "completed" or "incomplete"` - - `timezone: optional string` + The terminal status of the program output. - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + - `"completed"` - - `ApplyPatch object { type, allowed_callers }` + - `"incomplete"` - Allows the assistant to create, delete, or update files using unified diffs. + - `type: "program_output"` - - `type: "apply_patch"` + The item type. Always `program_output`. - The type of the tool. Always `apply_patch`. + - `"program_output"` - - `"apply_patch"` + - `metadata: Metadata` - - `allowed_callers: optional array of "direct" or "programmatic"` + 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 tool invocation context(s). + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - - `"direct"` + - `model: ResponsesModel` - - `"programmatic"` + Model ID used to generate the response, like `gpt-4o` or `o3`. OpenAI + offers a wide range of models with different capabilities, performance + characteristics, and price points. Refer to the [model guide](/docs/models) + to browse and compare available models. - - `type: "additional_tools"` + - `string` - The item type. Always `additional_tools`. + - `"gpt-5.6-sol" or "gpt-5.6-terra" or "gpt-5.6-luna" or 78 more` - - `"additional_tools"` + - `"gpt-5.6-sol"` - - `id: optional string` + - `"gpt-5.6-terra"` - The unique ID of this additional tools item. + - `"gpt-5.6-luna"` - - `Reasoning object { id, summary, type, 3 more }` + - `"gpt-5.4"` - 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). + - `"gpt-5.4-mini"` - - `id: string` + - `"gpt-5.4-nano"` - The unique identifier of the reasoning content. + - `"gpt-5.4-mini-2026-03-17"` - - `summary: array of SummaryTextContent` + - `"gpt-5.4-nano-2026-03-17"` - Reasoning summary content. + - `"gpt-5.3-chat-latest"` - - `text: string` + - `"gpt-5.2"` - A summary of the reasoning output from the model so far. + - `"gpt-5.2-2025-12-11"` - - `type: "summary_text"` + - `"gpt-5.2-chat-latest"` - The type of the object. Always `summary_text`. + - `"gpt-5.2-pro"` - - `"summary_text"` + - `"gpt-5.2-pro-2025-12-11"` - - `type: "reasoning"` + - `"gpt-5.1"` - The type of the object. Always `reasoning`. + - `"gpt-5.1-2025-11-13"` - - `"reasoning"` + - `"gpt-5.1-codex"` - - `content: optional array of object { text, type }` + - `"gpt-5.1-mini"` - Reasoning text content. + - `"gpt-5.1-chat-latest"` - - `text: string` + - `"gpt-5"` - The reasoning text from the model. + - `"gpt-5-mini"` - - `type: "reasoning_text"` + - `"gpt-5-nano"` - The type of the reasoning text. Always `reasoning_text`. + - `"gpt-5-2025-08-07"` - - `"reasoning_text"` + - `"gpt-5-mini-2025-08-07"` - - `encrypted_content: optional string` + - `"gpt-5-nano-2025-08-07"` - The encrypted content of the reasoning item. This is populated by default - for reasoning items returned by `POST /v1/responses` and WebSocket - `response.create` requests. + - `"gpt-5-chat-latest"` - - `status: optional "in_progress" or "completed" or "incomplete"` + - `"gpt-4.1"` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `"gpt-4.1-mini"` - - `"in_progress"` + - `"gpt-4.1-nano"` - - `"completed"` + - `"gpt-4.1-2025-04-14"` - - `"incomplete"` + - `"gpt-4.1-mini-2025-04-14"` - - `Compaction object { encrypted_content, type, id }` + - `"gpt-4.1-nano-2025-04-14"` - A compaction item generated by the [`v1/responses/compact` API](/docs/api-reference/responses/compact). + - `"o4-mini"` - - `encrypted_content: string` + - `"o4-mini-2025-04-16"` - The encrypted content of the compaction summary. + - `"o3"` - - `type: "compaction"` + - `"o3-2025-04-16"` - The type of the item. Always `compaction`. + - `"o3-mini"` - - `"compaction"` + - `"o3-mini-2025-01-31"` - - `id: optional string` + - `"o1"` - The ID of the compaction item. + - `"o1-2024-12-17"` - - `ImageGenerationCall object { id, result, status, type }` + - `"o1-preview"` - An image generation request made by the model. + - `"o1-preview-2024-09-12"` - - `id: string` + - `"o1-mini"` - The unique ID of the image generation call. + - `"o1-mini-2024-09-12"` - - `result: string` + - `"gpt-4o"` - The generated image encoded in base64. + - `"gpt-4o-2024-11-20"` - - `status: "in_progress" or "completed" or "generating" or "failed"` + - `"gpt-4o-2024-08-06"` - The status of the image generation call. + - `"gpt-4o-2024-05-13"` - - `"in_progress"` + - `"gpt-4o-audio-preview"` - - `"completed"` + - `"gpt-4o-audio-preview-2024-10-01"` - - `"generating"` + - `"gpt-4o-audio-preview-2024-12-17"` - - `"failed"` + - `"gpt-4o-audio-preview-2025-06-03"` - - `type: "image_generation_call"` + - `"gpt-4o-mini-audio-preview"` - The type of the image generation call. Always `image_generation_call`. + - `"gpt-4o-mini-audio-preview-2024-12-17"` - - `"image_generation_call"` + - `"gpt-4o-search-preview"` - - `CodeInterpreterCall object { id, code, container_id, 3 more }` + - `"gpt-4o-mini-search-preview"` - A tool call to run code. + - `"gpt-4o-search-preview-2025-03-11"` - - `id: string` + - `"gpt-4o-mini-search-preview-2025-03-11"` - The unique ID of the code interpreter tool call. + - `"chatgpt-4o-latest"` - - `code: string` + - `"codex-mini-latest"` - The code to run, or null if not available. + - `"gpt-4o-mini"` - - `container_id: string` + - `"gpt-4o-mini-2024-07-18"` - The ID of the container used to run the code. + - `"gpt-4-turbo"` - - `outputs: array of object { logs, type } or object { type, url }` + - `"gpt-4-turbo-2024-04-09"` - The outputs generated by the code interpreter, such as logs or images. - Can be null if no outputs are available. + - `"gpt-4-0125-preview"` - - `Logs object { logs, type }` + - `"gpt-4-turbo-preview"` - The logs output from the code interpreter. + - `"gpt-4-1106-preview"` - - `logs: string` + - `"gpt-4-vision-preview"` - The logs output from the code interpreter. + - `"gpt-4"` - - `type: "logs"` + - `"gpt-4-0314"` - The type of the output. Always `logs`. + - `"gpt-4-0613"` - - `"logs"` + - `"gpt-4-32k"` - - `Image object { type, url }` + - `"gpt-4-32k-0314"` - The image output from the code interpreter. + - `"gpt-4-32k-0613"` - - `type: "image"` + - `"gpt-3.5-turbo"` - The type of the output. Always `image`. + - `"gpt-3.5-turbo-16k"` - - `"image"` + - `"gpt-3.5-turbo-0301"` - - `url: string` + - `"gpt-3.5-turbo-0613"` - The URL of the image output from the code interpreter. + - `"gpt-3.5-turbo-1106"` - - `status: "in_progress" or "completed" or "incomplete" or 2 more` + - `"gpt-3.5-turbo-0125"` - The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. + - `"gpt-3.5-turbo-16k-0613"` - - `"in_progress"` + - `ResponsesOnlyModel = "o1-pro" or "o1-pro-2025-03-19" or "o3-pro" or 11 more` - - `"completed"` + - `"o1-pro"` - - `"incomplete"` + - `"o1-pro-2025-03-19"` - - `"interpreting"` + - `"o3-pro"` - - `"failed"` + - `"o3-pro-2025-06-10"` - - `type: "code_interpreter_call"` + - `"o3-deep-research"` - The type of the code interpreter tool call. Always `code_interpreter_call`. + - `"o3-deep-research-2025-06-26"` - - `"code_interpreter_call"` + - `"o4-mini-deep-research"` - - `LocalShellCall object { id, action, call_id, 2 more }` + - `"o4-mini-deep-research-2025-06-26"` - A tool call to run a command on the local shell. + - `"computer-use-preview"` - - `id: string` + - `"computer-use-preview-2025-03-11"` - The unique ID of the local shell call. + - `"gpt-5-codex"` - - `action: object { command, env, type, 3 more }` + - `"gpt-5-pro"` - Execute a shell command on the server. + - `"gpt-5-pro-2025-10-06"` - - `command: array of string` + - `"gpt-5.1-codex-max"` - The command to run. + - `object: "response"` - - `env: map[string]` + The object type of this resource - always set to `response`. - Environment variables to set for the command. + - `"response"` - - `type: "exec"` + - `output: array of ResponseOutputItem` - The type of the local shell action. Always `exec`. + An array of content items generated by the model. - - `"exec"` + - The length and order of items in the `output` array is dependent + on the model's response. + - Rather than accessing the first item in the `output` array and + assuming it's an `assistant` message with the content generated by + the model, you might consider using the `output_text` property where + supported in SDKs. - - `timeout_ms: optional number` + - `ResponseOutputMessage object { id, content, role, 3 more }` - Optional timeout in milliseconds for the command. + An output message from the model. - - `user: optional string` + - `FileSearchCall object { id, queries, status, 2 more }` - Optional user to run the command as. + The results of a file search tool call. See the + [file search guide](/docs/guides/tools-file-search) for more information. - - `working_directory: optional string` + - `id: string` - Optional working directory to run the command in. + The unique ID of the file search tool call. - - `call_id: string` + - `queries: array of string` - The unique ID of the local shell tool call generated by the model. + The queries used to search for files. - - `status: "in_progress" or "completed" or "incomplete"` + - `status: "in_progress" or "searching" or "completed" or 2 more` - The status of the local shell call. + The status of the file search tool call. One of `in_progress`, + `searching`, `incomplete` or `failed`, - `"in_progress"` + - `"searching"` + - `"completed"` - `"incomplete"` - - `type: "local_shell_call"` - - The type of the local shell call. Always `local_shell_call`. - - - `"local_shell_call"` + - `"failed"` - - `LocalShellCallOutput object { id, output, type, status }` + - `type: "file_search_call"` - The output of a local shell tool call. + The type of the file search tool call. Always `file_search_call`. - - `id: string` + - `"file_search_call"` - The unique ID of the local shell tool call generated by the model. + - `results: optional array of object { attributes, file_id, filename, 2 more }` - - `output: string` + The results of the file search tool call. - A JSON string of the output of the local shell tool call. + - `attributes: optional map[string or number or boolean]` - - `type: "local_shell_call_output"` + 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 type of the local shell tool call output. Always `local_shell_call_output`. + - `string` - - `"local_shell_call_output"` + - `number` - - `status: optional "in_progress" or "completed" or "incomplete"` + - `boolean` - The status of the item. One of `in_progress`, `completed`, or `incomplete`. + - `file_id: optional string` - - `"in_progress"` + The unique ID of the file. - - `"completed"` + - `filename: optional string` - - `"incomplete"` + The name of the file. - - `ShellCall object { action, call_id, type, 4 more }` + - `score: optional number` - A tool representing a request to execute one or more shell commands. + The relevance score of the file - a value between 0 and 1. - - `action: object { commands, max_output_length, timeout_ms }` + - `text: optional string` - The shell commands and limits that describe how to run the tool call. + The text that was retrieved from the file. - - `commands: array of string` + - `FunctionCall object { arguments, call_id, name, 5 more }` - Ordered shell commands for the execution environment to run. + A tool call to run a function. See the + [function calling guide](/docs/guides/function-calling) for more information. - - `max_output_length: optional number` + - `arguments: string` - Maximum number of UTF-8 characters to capture from combined stdout and stderr output. + A JSON string of the arguments to pass to the function. - - `timeout_ms: optional number` + - `call_id: string` - Maximum wall-clock time in milliseconds to allow the shell commands to run. + The unique ID of the function tool call generated by the model. - - `call_id: string` + - `name: string` - The unique ID of the shell tool call generated by the model. + The name of the function to run. - - `type: "shell_call"` + - `type: "function_call"` - The type of the item. Always `shell_call`. + The type of the function tool call. Always `function_call`. - - `"shell_call"` + - `"function_call"` - `id: optional string` - The unique ID of the shell tool call. Populated when this item is returned via API. + The unique ID of the function tool call. - `caller: optional object { type } or object { caller_id, type }` @@ -37921,8 +37961,6 @@ Learn when and how to compact long-running conversations in the [conversation st - `type: "direct"` - The caller type. Always `direct`. - - `"direct"` - `Program object { caller_id, type }` @@ -37933,21 +37971,16 @@ Learn when and how to compact long-running conversations in the [conversation st - `type: "program"` - The caller type. Always `program`. - - `"program"` - - `environment: optional LocalEnvironment or ContainerReference` - - The environment to execute the shell commands in. - - - `LocalEnvironment object { type, skills }` + - `namespace: optional string` - - `ContainerReference object { container_id, type }` + The namespace of the function to run. - `status: optional "in_progress" or "completed" or "incomplete"` - The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - `"in_progress"` @@ -37955,63 +37988,57 @@ Learn when and how to compact long-running conversations in the [conversation st - `"incomplete"` - - `ShellCallOutput object { call_id, output, type, 4 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` + - `FunctionCallOutput object { id, call_id, output, 4 more }` - Captured chunks of stdout and stderr output, along with their associated outcomes. + - `id: string` - - `outcome: object { type } or object { exit_code, type }` + The unique ID of the function call tool output. - The exit or timeout outcome associated with this shell call. + - `call_id: string` - - `Timeout object { type }` + The unique ID of the function tool call generated by the model. - Indicates that the shell call exceeded its configured time limit. + - `output: string or array of ResponseInputText or ResponseInputImage or ResponseInputFile` - - `type: "timeout"` + The output from the function call generated by your code. + Can be a string or an list of output content. - The outcome type. Always `timeout`. + - `StringOutput = string` - - `"timeout"` + A string of the output of the function call. - - `Exit object { exit_code, type }` + - `OutputContentList = array of ResponseInputText or ResponseInputImage or ResponseInputFile` - Indicates that the shell commands finished and returned an exit code. + Text, image, or file output of the function call. - - `exit_code: number` + - `ResponseInputText object { text, type, prompt_cache_breakpoint }` - The exit code returned by the shell process. + A text input to the model. - - `type: "exit"` + - `ResponseInputImage object { detail, type, file_id, 2 more }` - The outcome type. Always `exit`. + An image input to the model. Learn about [image inputs](/docs/guides/vision). - - `"exit"` + - `ResponseInputFile object { type, detail, file_data, 4 more }` - - `stderr: string` + A file input to the model. - Captured stderr output for the shell call. + - `status: "in_progress" or "completed" or "incomplete"` - - `stdout: string` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - Captured stdout output for the shell call. + - `"in_progress"` - - `type: "shell_call_output"` + - `"completed"` - The type of the item. Always `shell_call_output`. + - `"incomplete"` - - `"shell_call_output"` + - `type: "function_call_output"` - - `id: optional string` + The type of the function tool call output. Always `function_call_output`. - The unique ID of the shell tool call output. Populated when this item is returned via API. + - `"function_call_output"` - `caller: optional object { type } or object { caller_id, type }` @@ -38037,314 +38064,352 @@ Learn when and how to compact long-running conversations in the [conversation st - `"program"` - - `max_output_length: optional number` + - `created_by: optional string` - The maximum number of UTF-8 characters captured for this shell call's combined output. + The identifier of the actor that created the item. - - `status: optional "in_progress" or "completed" or "incomplete"` + - `WebSearchCall object { id, action, status, type }` - The status of the shell call output. + The results of a web search tool call. See the + [web search guide](/docs/guides/tools-web-search) for more information. - - `"in_progress"` + - `id: string` - - `"completed"` + The unique ID of the web search tool call. - - `"incomplete"` + - `action: object { type, queries, query, sources } or object { type, url } or object { pattern, type, url }` - - `ApplyPatchCall object { call_id, operation, status, 3 more }` + 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 tool call representing a request to create, delete, or update files using diff patches. + - `Search object { type, queries, query, sources }` - - `call_id: string` + Action type "search" - Performs a web search query. - The unique ID of the apply patch tool call generated by the model. + - `type: "search"` - - `operation: object { diff, path, type } or object { path, type } or object { diff, path, type }` + The action type. - The specific create, delete, or update instruction for the apply_patch tool call. + - `"search"` - - `CreateFile object { diff, path, type }` + - `queries: optional array of string` - Instruction for creating a new file via the apply_patch tool. + The search queries. - - `diff: string` + - `query: optional string` - Unified diff content to apply when creating the file. + The search query. - - `path: string` + - `sources: optional array of object { type, url }` - Path of the file to create relative to the workspace root. + The sources used in the search. - - `type: "create_file"` + - `type: "url"` - The operation type. Always `create_file`. + The type of source. Always `url`. - - `"create_file"` + - `"url"` - - `DeleteFile object { path, type }` + - `url: string` - Instruction for deleting an existing file via the apply_patch tool. + The URL of the source. - - `path: string` + - `OpenPage object { type, url }` - Path of the file to delete relative to the workspace root. + Action type "open_page" - Opens a specific URL from search results. - - `type: "delete_file"` + - `type: "open_page"` - The operation type. Always `delete_file`. + The action type. - - `"delete_file"` + - `"open_page"` - - `UpdateFile object { diff, path, type }` + - `url: optional string` - Instruction for updating an existing file via the apply_patch tool. + The URL opened by the model. - - `diff: string` + - `FindInPage object { pattern, type, url }` - Unified diff content to apply to the existing file. + Action type "find_in_page": Searches for a pattern within a loaded page. - - `path: string` + - `pattern: string` - Path of the file to update relative to the workspace root. + The pattern or text to search for within the page. - - `type: "update_file"` + - `type: "find_in_page"` - The operation type. Always `update_file`. + The action type. - - `"update_file"` + - `"find_in_page"` - - `status: "in_progress" or "completed"` + - `url: string` - The status of the apply patch tool call. One of `in_progress` or `completed`. + 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"` - - `type: "apply_patch_call"` + - `"failed"` - The type of the item. Always `apply_patch_call`. + - `type: "web_search_call"` - - `"apply_patch_call"` + The type of the web search tool call. Always `web_search_call`. - - `id: optional string` + - `"web_search_call"` - The unique ID of the apply patch tool call. Populated when this item is returned via API. + - `ComputerCall object { id, call_id, pending_safety_checks, 4 more }` - - `caller: optional object { type } or object { caller_id, type }` + A tool call to a computer use tool. See the + [computer use guide](/docs/guides/tools-computer-use) for more information. - The execution context that produced this tool call. + - `id: string` - - `Direct object { type }` + The unique ID of the computer call. - - `type: "direct"` + - `call_id: string` - The caller type. Always `direct`. + An identifier used when responding to the tool call with output. - - `"direct"` + - `pending_safety_checks: array of object { id, code, message }` - - `Program object { caller_id, type }` + The pending safety checks for the computer call. - - `caller_id: string` + - `id: string` - The call ID of the program item that produced this tool call. + The ID of the pending safety check. - - `type: "program"` + - `code: optional string` - The caller type. Always `program`. + The type of the pending safety check. - - `"program"` + - `message: optional string` - - `ApplyPatchCallOutput object { call_id, status, type, 3 more }` + Details about the pending safety check. - The streamed output emitted by an apply patch tool call. + - `status: "in_progress" or "completed" or "incomplete"` - - `call_id: string` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - The unique ID of the apply patch tool call generated by the model. + - `"in_progress"` - - `status: "completed" or "failed"` + - `"completed"` - The status of the apply patch tool call output. One of `completed` or `failed`. + - `"incomplete"` - - `"completed"` + - `type: "computer_call"` - - `"failed"` + The type of the computer call. Always `computer_call`. - - `type: "apply_patch_call_output"` + - `"computer_call"` - The type of the item. Always `apply_patch_call_output`. + - `action: optional ComputerAction` - - `"apply_patch_call_output"` + A click action. - - `id: optional string` + - `actions: optional ComputerActionList` - The unique ID of the apply patch tool call output. Populated when this item is returned via API. + Flattened batched actions for `computer_use`. Each action includes an + `type` discriminator and action-specific fields. - - `caller: optional object { type } or object { caller_id, type }` + - `ComputerCallOutput object { id, call_id, output, 4 more }` - The execution context that produced this tool call. + - `id: string` - - `Direct object { type }` + The unique ID of the computer call tool output. - - `type: "direct"` + - `call_id: string` - The caller type. Always `direct`. + The ID of the computer tool call that produced the output. - - `"direct"` + - `output: ResponseComputerToolCallOutputScreenshot` - - `Program object { caller_id, type }` + A computer screenshot image used with the computer use tool. - - `caller_id: string` + - `status: "completed" or "incomplete" or "failed" or "in_progress"` - The call ID of the program item that produced this tool call. + The status of the message input. One of `in_progress`, `completed`, or + `incomplete`. Populated when input items are returned via API. - - `type: "program"` + - `"completed"` - The caller type. Always `program`. + - `"incomplete"` - - `"program"` + - `"failed"` - - `output: optional string` + - `"in_progress"` - Optional human-readable log text from the apply patch tool (e.g., patch results or errors). + - `type: "computer_call_output"` - - `McpListTools object { id, server_label, tools, 2 more }` + The type of the computer tool call output. Always `computer_call_output`. - A list of tools available on an MCP server. + - `"computer_call_output"` + + - `acknowledged_safety_checks: optional array of object { id, code, message }` + + The safety checks reported by the API that have been acknowledged by the + developer. - `id: string` - The unique ID of the list. + The ID of the pending safety check. - - `server_label: string` + - `code: optional string` - The label of the MCP server. + The type of the pending safety check. - - `tools: array of object { input_schema, name, annotations, description }` + - `message: optional string` - The tools available on the server. + Details about the pending safety check. - - `input_schema: unknown` + - `created_by: optional string` - The JSON schema describing the tool's input. + The identifier of the actor that created the item. - - `name: string` + - `Reasoning object { id, summary, type, 3 more }` - The name of the tool. + 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). - - `annotations: optional unknown` + - `id: string` - Additional annotations about the tool. + The unique identifier of the reasoning content. - - `description: optional string` + - `summary: array of SummaryTextContent` - The description of the tool. + Reasoning summary content. - - `type: "mcp_list_tools"` + - `text: string` - The type of the item. Always `mcp_list_tools`. + A summary of the reasoning output from the model so far. - - `"mcp_list_tools"` + - `type: "summary_text"` - - `error: optional string` + The type of the object. Always `summary_text`. - Error message if the server could not list tools. + - `type: "reasoning"` - - `McpApprovalRequest object { id, arguments, name, 2 more }` + The type of the object. Always `reasoning`. - A request for human approval of a tool invocation. + - `"reasoning"` - - `id: string` + - `content: optional array of object { text, type }` - The unique ID of the approval request. + Reasoning text content. - - `arguments: string` + - `text: string` - A JSON string of arguments for the tool. + The reasoning text from the model. - - `name: string` + - `type: "reasoning_text"` - The name of the tool to run. + The type of the reasoning text. Always `reasoning_text`. - - `server_label: string` + - `"reasoning_text"` - The label of the MCP server making the request. + - `encrypted_content: optional string` - - `type: "mcp_approval_request"` + The encrypted content of the reasoning item. This is populated by default + for reasoning items returned by `POST /v1/responses` and WebSocket + `response.create` requests. + + - `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"` + + - `Program object { id, call_id, code, 2 more }` + + - `id: string` + + The unique ID of the program item. - The type of the item. Always `mcp_approval_request`. + - `call_id: string` - - `"mcp_approval_request"` + The stable call ID of the program item. - - `McpApprovalResponse object { approval_request_id, approve, type, 2 more }` + - `code: string` - A response to an MCP approval request. + The JavaScript source executed by programmatic tool calling. - - `approval_request_id: string` + - `fingerprint: string` - The ID of the approval request being answered. + Opaque program replay fingerprint that must be round-tripped. - - `approve: boolean` + - `type: "program"` - Whether the request was approved. + The type of the item. Always `program`. - - `type: "mcp_approval_response"` + - `"program"` - The type of the item. Always `mcp_approval_response`. + - `ProgramOutput object { id, call_id, result, 2 more }` - - `"mcp_approval_response"` + - `id: string` - - `id: optional string` + The unique ID of the program output item. - The unique ID of the approval response + - `call_id: string` - - `reason: optional string` + The call ID of the program item. - Optional reason for the decision. + - `result: string` - - `McpCall object { id, arguments, name, 6 more }` + The result produced by the program item. - An invocation of a tool on an MCP server. + - `status: "completed" or "incomplete"` - - `id: string` + The terminal status of the program output item. - The unique ID of the tool call. + - `"completed"` - - `arguments: string` + - `"incomplete"` - A JSON string of the arguments passed to the tool. + - `type: "program_output"` - - `name: string` + The type of the item. Always `program_output`. - The name of the tool that was run. + - `"program_output"` - - `server_label: string` + - `ToolSearchCall object { id, arguments, call_id, 4 more }` - The label of the MCP server running the tool. + - `id: string` - - `type: "mcp_call"` + The unique ID of the tool search call item. - The type of the item. Always `mcp_call`. + - `arguments: unknown` - - `"mcp_call"` + Arguments used for the tool search call. - - `approval_request_id: optional string` + - `call_id: 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. + The unique ID of the tool search call generated by the model. - - `error: optional string` + - `execution: "server" or "client"` - The error from the tool call, if any. + Whether tool search was executed by the server or by the client. - - `output: optional string` + - `"server"` - The output from the tool call. + - `"client"` - - `status: optional "in_progress" or "completed" or "incomplete" or 2 more` + - `status: "in_progress" or "completed" or "incomplete"` - The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. + The status of the tool search call item that was recorded. - `"in_progress"` @@ -38352,851 +38417,896 @@ Learn when and how to compact long-running conversations in the [conversation st - `"incomplete"` - - `"calling"` + - `type: "tool_search_call"` - - `"failed"` + The type of the item. Always `tool_search_call`. - - `CustomToolCallOutput object { call_id, output, type, 2 more }` + - `"tool_search_call"` - The output of a custom tool call from your code, being sent back to the model. + - `created_by: optional string` + + The identifier of the actor that created the item. + + - `ToolSearchOutput object { id, call_id, execution, 4 more }` + + - `id: string` + + The unique ID of the tool search output item. - `call_id: string` - The call ID, used to map this custom tool call output to a custom tool call. + The unique ID of the tool search call generated by the model. - - `output: string or array of ResponseInputText or ResponseInputImage or ResponseInputFile` + - `execution: "server" or "client"` - The output from the custom tool call generated by your code. - Can be a string or an list of output content. + Whether tool search was executed by the server or by the client. - - `StringOutput = string` + - `"server"` - A string of the output of the custom tool call. + - `"client"` - - `OutputContentList = array of ResponseInputText or ResponseInputImage or ResponseInputFile` + - `status: "in_progress" or "completed" or "incomplete"` - Text, image, or file output of the custom tool call. + The status of the tool search output item that was recorded. - - `ResponseInputText object { text, type, prompt_cache_breakpoint }` + - `"in_progress"` - A text input to the model. + - `"completed"` - - `ResponseInputImage object { detail, type, file_id, 2 more }` + - `"incomplete"` - An image input to the model. Learn about [image inputs](/docs/guides/vision). + - `tools: array of object { name, parameters, strict, 5 more } or object { type, vector_store_ids, filters, 2 more } or object { type } or 13 more` - - `ResponseInputFile object { type, detail, file_data, 4 more }` + The loaded tool definitions returned by tool search. - A file input to the model. + - `Function object { name, parameters, strict, 5 more }` - - `type: "custom_tool_call_output"` + Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). - The type of the custom tool call output. Always `custom_tool_call_output`. + - `name: string` - - `"custom_tool_call_output"` + The name of the function to call. - - `id: optional string` + - `parameters: map[unknown]` - The unique ID of the custom tool call output in the OpenAI platform. + A JSON schema object describing the parameters of the function. - - `caller: optional object { type } or object { caller_id, type }` + - `strict: boolean` - The execution context that produced this tool call. + Whether strict parameter validation is enforced for this function tool. - - `Direct object { type }` + - `type: "function"` - - `type: "direct"` + The type of the function tool. Always `function`. - The caller type. Always `direct`. + - `"function"` + + - `allowed_callers: optional array of "direct" or "programmatic"` + + The tool invocation context(s). - `"direct"` - - `Program object { caller_id, type }` + - `"programmatic"` - - `caller_id: string` + - `defer_loading: optional boolean` - The call ID of the program item that produced this tool call. + Whether this function is deferred and loaded via tool search. - - `type: "program"` + - `description: optional string` - The caller type. Always `program`. + A description of the function. Used by the model to determine whether or not to call the function. - - `"program"` + - `output_schema: optional map[unknown]` - - `CustomToolCall object { call_id, input, name, 4 more }` + A JSON schema object describing the JSON value encoded in string outputs for this function. - A call to a custom tool created by the model. + - `FileSearch object { type, vector_store_ids, filters, 2 more }` - - `call_id: 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). - An identifier used to map this custom tool call to a tool call output. + - `type: "file_search"` - - `input: string` + The type of the file search tool. Always `file_search`. - The input for the custom tool call generated by the model. + - `"file_search"` - - `name: string` + - `vector_store_ids: array of string` - The name of the custom tool being called. + The IDs of the vector stores to search. - - `type: "custom_tool_call"` + - `filters: optional ComparisonFilter or CompoundFilter` - The type of the custom tool call. Always `custom_tool_call`. + A filter to apply. - - `"custom_tool_call"` + - `ComparisonFilter object { key, type, value }` - - `id: optional string` + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - The unique ID of the custom tool call in the OpenAI platform. + - `CompoundFilter object { filters, type }` - - `caller: optional object { type } or object { caller_id, type }` + Combine multiple filters using `and` or `or`. - The execution context that produced this tool call. + - `max_num_results: optional number` - - `Direct object { type }` + The maximum number of results to return. This number should be between 1 and 50 inclusive. - - `type: "direct"` + - `ranking_options: optional object { hybrid_search, ranker, score_threshold }` - - `"direct"` + Ranking options for search. - - `Program object { caller_id, type }` + - `hybrid_search: optional object { embedding_weight, text_weight }` - - `caller_id: string` + Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. - The call ID of the program item that produced this tool call. + - `embedding_weight: number` - - `type: "program"` + The weight of the embedding in the reciprocal ranking fusion. - - `"program"` + - `text_weight: number` - - `namespace: optional string` + The weight of the text in the reciprocal ranking fusion. - The namespace of the custom tool being called. + - `ranker: optional "auto" or "default-2024-11-15"` - - `CompactionTrigger object { type }` + The ranker to use for the file search. - Compacts the current context. Must be the final input item. + - `"auto"` - - `type: "compaction_trigger"` + - `"default-2024-11-15"` - The type of the item. Always `compaction_trigger`. + - `score_threshold: optional number` - - `"compaction_trigger"` + 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. - - `ItemReference object { id, type }` + - `Computer object { type }` - An internal identifier for an item to reference. + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `id: string` + - `type: "computer"` - The ID of the item to reference. + The type of the computer tool. Always `computer`. - - `type: optional "item_reference"` + - `"computer"` - The type of item to reference. Always `item_reference`. + - `ComputerUsePreview object { display_height, display_width, environment, type }` - - `"item_reference"` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `Program object { id, call_id, code, 2 more }` + - `display_height: number` - - `id: string` + The height of the computer display. - The unique ID of this program item. + - `display_width: number` - - `call_id: string` + The width of the computer display. - The stable call ID of the program item. + - `environment: "windows" or "mac" or "linux" or 2 more` - - `code: string` + The type of computer environment to control. - The JavaScript source executed by programmatic tool calling. + - `"windows"` - - `fingerprint: string` + - `"mac"` - Opaque program replay fingerprint that must be round-tripped. + - `"linux"` - - `type: "program"` + - `"ubuntu"` - The item type. Always `program`. + - `"browser"` - - `"program"` + - `type: "computer_use_preview"` - - `ProgramOutput object { id, call_id, result, 2 more }` + The type of the computer use tool. Always `computer_use_preview`. - - `id: string` + - `"computer_use_preview"` - The unique ID of this program output item. + - `WebSearch object { type, filters, search_context_size, user_location }` - - `call_id: string` + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](/docs/guides/tools-web-search). - The call ID of the program item. + - `type: "web_search" or "web_search_2025_08_26"` - - `result: string` + The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. - The result produced by the program item. + - `"web_search"` - - `status: "completed" or "incomplete"` + - `"web_search_2025_08_26"` - The terminal status of the program output. + - `filters: optional object { allowed_domains }` - - `"completed"` + Filters for the search. - - `"incomplete"` + - `allowed_domains: optional array of string` - - `type: "program_output"` + Allowed domains for the search. If not provided, all domains are allowed. + Subdomains of the provided domains are allowed as well. - The item type. Always `program_output`. + Example: `["pubmed.ncbi.nlm.nih.gov"]` - - `"program_output"` + - `search_context_size: optional "low" or "medium" or "high"` -- `instructions: 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. - A system (or developer) message inserted into the model's context. - When used along with `previous_response_id`, the instructions from a previous response will not be carried over to the next response. This makes it simple to swap out system (or developer) messages in new responses. + - `"low"` -- `previous_response_id: optional string` + - `"medium"` - The unique ID of the previous response to the model. Use this to create multi-turn conversations. Learn more about [conversation state](/docs/guides/conversation-state). Cannot be used in conjunction with `conversation`. + - `"high"` -- `prompt_cache_key: optional string` + - `user_location: optional object { city, country, region, 2 more }` - A key to use when reading from or writing to the prompt cache. + The approximate location of the user. -- `prompt_cache_options: optional object { mode, ttl }` + - `city: optional string` - Options for prompt caching. Supported for `gpt-5.6` and later models. By default, OpenAI automatically chooses one implicit cache breakpoint. You can add explicit breakpoints to content blocks with `prompt_cache_breakpoint`. Each request can write up to four breakpoints. For cache matching, OpenAI considers up to the latest 80 breakpoints in the conversation, without a content-block lookback limit. Set `mode` to `explicit` to disable the implicit breakpoint. The `ttl` defaults to `30m`, which is currently the only supported value. See the [prompt caching guide](/docs/guides/prompt-caching) for current details. + Free text input for the city of the user, e.g. `San Francisco`. - - `mode: optional "implicit" or "explicit"` + - `country: optional string` - Controls whether OpenAI automatically creates an implicit cache breakpoint. Defaults to `implicit`. With `implicit`, OpenAI creates one implicit breakpoint and writes up to the latest three explicit breakpoints in the request. With `explicit`, OpenAI does not create an implicit breakpoint and writes up to the latest four explicit breakpoints. If there are no explicit breakpoints, the request does not use prompt caching. + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - - `"implicit"` + - `region: optional string` - - `"explicit"` + Free text input for the region of the user, e.g. `California`. - - `ttl: optional "30m"` + - `timezone: optional string` - The minimum lifetime applied to every implicit and explicit cache breakpoint written by the request. Defaults to `30m`, which is currently the only supported value. The backend may retain cache entries for longer. + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - - `"30m"` + - `type: optional "approximate"` -- `prompt_cache_retention: optional "in_memory" or "24h"` + The type of location approximation. Always `approximate`. - How long to retain a prompt cache entry created by this request. + - `"approximate"` - - `"in_memory"` + - `Mcp object { server_label, type, allowed_callers, 9 more }` - - `"24h"` + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](/docs/guides/tools-remote-mcp). -- `service_tier: optional "auto" or "default" or "flex" or "priority"` + - `server_label: string` - The service tier to use for this request. + A label for this MCP server, used to identify it in tool calls. - - `"auto"` + - `type: "mcp"` - - `"default"` + The type of the MCP tool. Always `mcp`. - - `"flex"` + - `"mcp"` - - `"priority"` + - `allowed_callers: optional array of "direct" or "programmatic"` -### Returns + The tool invocation context(s). -- `CompactedResponse object { id, created_at, object, 2 more }` + - `"direct"` - - `id: string` + - `"programmatic"` - The unique identifier for the compacted response. + - `allowed_tools: optional array of string or object { read_only, tool_names }` - - `created_at: number` + List of allowed tool names or a filter object. - Unix timestamp (in seconds) when the compacted conversation was created. + - `McpAllowedTools = array of string` - - `object: "response.compaction"` + A string array of allowed tool names - The object type. Always `response.compaction`. + - `McpToolFilter object { read_only, tool_names }` - - `"response.compaction"` + A filter object to specify which tools are allowed. - - `output: array of Message or object { id, call_id, code, 2 more } or object { id, call_id, result, 2 more } or 25 more` + - `read_only: optional boolean` - The compacted list of output items. + 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. - - `Message object { id, content, role, 3 more }` + - `tool_names: optional array of string` - A message to or from the model. + List of allowed tool names. - - `id: string` + - `authorization: optional string` - The unique ID of the message. + 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. - - `content: array of ResponseInputText or ResponseOutputText or TextContent or 6 more` + - `connector_id: optional "connector_dropbox" or "connector_gmail" or "connector_googlecalendar" or 5 more` - The content of the message + Identifier for service connectors, like those available in ChatGPT. One of + `server_url`, `connector_id`, or `tunnel_id` must be provided. Learn more + about service connectors [here](/docs/guides/tools-remote-mcp#connectors). - - `ResponseInputText object { text, type, prompt_cache_breakpoint }` + Currently supported `connector_id` values are: - A text input to the model. + - 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` - - `text: string` + - `"connector_dropbox"` - The text input to the model. + - `"connector_gmail"` - - `type: "input_text"` + - `"connector_googlecalendar"` - The type of the input item. Always `input_text`. + - `"connector_googledrive"` - - `"input_text"` + - `"connector_microsoftteams"` - - `prompt_cache_breakpoint: optional object { mode }` + - `"connector_outlookcalendar"` - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + - `"connector_outlookemail"` - - `mode: "explicit"` + - `"connector_sharepoint"` - The breakpoint mode. Always `explicit`. + - `defer_loading: optional boolean` - - `"explicit"` + Whether this MCP tool is deferred and discovered via tool search. - - `ResponseOutputText object { annotations, logprobs, text, type }` + - `headers: optional map[string]` - A text output from the model. + Optional HTTP headers to send to the MCP server. Use for authentication + or other purposes. - - `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 }` + - `require_approval: optional object { always, never } or "always" or "never"` - The annotations of the text output. + Specify which of the MCP server's tools require approval. - - `FileCitation object { file_id, filename, index, type }` + - `McpToolApprovalFilter object { always, never }` - A citation to a 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. - - `file_id: string` + - `always: optional object { read_only, tool_names }` - The ID of the file. + A filter object to specify which tools are allowed. - - `filename: string` + - `read_only: optional boolean` - The filename of the file cited. + 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. - - `index: number` + - `tool_names: optional array of string` - The index of the file in the list of files. + List of allowed tool names. - - `type: "file_citation"` + - `never: optional object { read_only, tool_names }` - The type of the file citation. Always `file_citation`. + A filter object to specify which tools are allowed. - - `"file_citation"` + - `read_only: optional boolean` - - `URLCitation object { end_index, start_index, title, 2 more }` + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. - A citation for a web resource used to generate a model response. + - `tool_names: optional array of string` - - `end_index: number` + List of allowed tool names. - The index of the last character of the URL citation in the message. + - `McpToolApprovalSetting = "always" or "never"` - - `start_index: number` + Specify a single approval policy for all tools. One of `always` or + `never`. When set to `always`, all tools will require approval. When + set to `never`, all tools will not require approval. - The index of the first character of the URL citation in the message. + - `"always"` - - `title: string` + - `"never"` - The title of the web resource. + - `server_description: optional string` - - `type: "url_citation"` + Optional description of the MCP server, used to provide more context. - The type of the URL citation. Always `url_citation`. + - `server_url: optional string` - - `"url_citation"` + The URL for the MCP server. One of `server_url`, `connector_id`, or + `tunnel_id` must be provided. - - `url: string` + - `tunnel_id: optional string` - The URL of the web resource. + The Secure MCP Tunnel ID to use instead of a direct server URL. One of + `server_url`, `connector_id`, or `tunnel_id` must be provided. - - `ContainerFileCitation object { container_id, end_index, file_id, 3 more }` + - `CodeInterpreter object { container, type, allowed_callers }` - A citation for a container file used to generate a model response. + A tool that runs Python code to help generate a response to a prompt. - - `container_id: string` + - `container: string or object { type, file_ids, memory_limit, network_policy }` - The ID of the container file. + 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. - - `end_index: number` + - `string` - The index of the last character of the container file citation in the message. + The container ID. - - `file_id: string` + - `CodeInterpreterToolAuto object { type, file_ids, memory_limit, network_policy }` - The ID of the file. + Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. - - `filename: string` + - `type: "auto"` - The filename of the container file cited. + Always `auto`. - - `start_index: number` + - `"auto"` - The index of the first character of the container file citation in the message. + - `file_ids: optional array of string` - - `type: "container_file_citation"` + An optional list of uploaded files to make available to your code. - The type of the container file citation. Always `container_file_citation`. + - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` - - `"container_file_citation"` + The memory limit for the code interpreter container. - - `FilePath object { file_id, index, type }` + - `"1g"` - A path to a file. + - `"4g"` + + - `"16g"` + + - `"64g"` + + - `network_policy: optional ContainerNetworkPolicyDisabled or ContainerNetworkPolicyAllowlist` - - `file_id: string` + Network access policy for the container. - The ID of the file. + - `ContainerNetworkPolicyDisabled object { type }` - - `index: number` + - `ContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` - The index of the file in the list of files. + - `type: "code_interpreter"` - - `type: "file_path"` + The type of the code interpreter tool. Always `code_interpreter`. - The type of the file path. Always `file_path`. + - `"code_interpreter"` - - `"file_path"` + - `allowed_callers: optional array of "direct" or "programmatic"` - - `logprobs: array of object { token, bytes, logprob, top_logprobs }` + The tool invocation context(s). - - `token: string` + - `"direct"` - - `bytes: array of number` + - `"programmatic"` - - `logprob: number` + - `ProgrammaticToolCalling object { type }` - - `top_logprobs: array of object { token, bytes, logprob }` + - `type: "programmatic_tool_calling"` - - `token: string` + The type of the tool. Always `programmatic_tool_calling`. - - `bytes: array of number` + - `"programmatic_tool_calling"` - - `logprob: number` + - `ImageGeneration object { type, action, background, 9 more }` - - `text: string` + A tool that generates images using the GPT image models. - The text output from the model. + - `type: "image_generation"` - - `type: "output_text"` + The type of the image generation tool. Always `image_generation`. - The type of the output text. Always `output_text`. + - `"image_generation"` - - `"output_text"` + - `action: optional "generate" or "edit" or "auto"` - - `TextContent object { text, type }` + Whether to generate a new image or edit an existing image. Default: `auto`. - A text content. + - `"generate"` - - `text: string` + - `"edit"` - - `type: "text"` + - `"auto"` - - `"text"` + - `background: optional "transparent" or "opaque" or "auto"` - - `SummaryTextContent object { text, type }` + Background type for the generated image. One of `transparent`, + `opaque`, or `auto`. Default: `auto`. - A summary text from the model. + - `"transparent"` - - `text: string` + - `"opaque"` - A summary of the reasoning output from the model so far. + - `"auto"` - - `type: "summary_text"` + - `input_fidelity: optional "high" or "low"` - The type of the object. Always `summary_text`. + 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`. - - `"summary_text"` + - `"high"` - - `ReasoningText object { text, type }` + - `"low"` - Reasoning text from the model. + - `input_image_mask: optional object { file_id, image_url }` - - `text: string` + Optional mask for inpainting. Contains `image_url` + (string, optional) and `file_id` (string, optional). - The reasoning text from the model. + - `file_id: optional string` - - `type: "reasoning_text"` + File ID for the mask image. - The type of the reasoning text. Always `reasoning_text`. + - `image_url: optional string` - - `"reasoning_text"` + Base64-encoded mask image. - - `ResponseOutputRefusal object { refusal, type }` + - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` - A refusal from the model. + The image generation model to use. Default: `gpt-image-1`. - - `refusal: string` + - `string` - The refusal explanation from the model. + - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` - - `type: "refusal"` + The image generation model to use. Default: `gpt-image-1`. - The type of the refusal. Always `refusal`. + - `"gpt-image-1"` - - `"refusal"` + - `"gpt-image-1-mini"` - - `ResponseInputImage object { detail, type, file_id, 2 more }` + - `"gpt-image-1.5"` - An image input to the model. Learn about [image inputs](/docs/guides/vision). + - `moderation: optional "auto" or "low"` - - `detail: "low" or "high" or "auto" or "original"` + Moderation level for the generated image. Default: `auto`. - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + - `"auto"` - `"low"` - - `"high"` + - `output_compression: optional number` - - `"auto"` + Compression level for the output image. Default: 100. - - `"original"` + - `output_format: optional "png" or "webp" or "jpeg"` - - `type: "input_image"` + The output format of the generated image. One of `png`, `webp`, or + `jpeg`. Default: `png`. - The type of the input item. Always `input_image`. + - `"png"` - - `"input_image"` + - `"webp"` - - `file_id: optional string` + - `"jpeg"` - The ID of the file to be sent to the model. + - `partial_images: optional number` - - `image_url: optional string` + Number of partial images to generate in streaming mode, from 0 (default value) to 3. - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + - `quality: optional "low" or "medium" or "high" or "auto"` - - `prompt_cache_breakpoint: optional object { mode }` + The quality of the generated image. One of `low`, `medium`, `high`, + or `auto`. Default: `auto`. - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + - `"low"` - - `mode: "explicit"` + - `"medium"` - The breakpoint mode. Always `explicit`. + - `"high"` - - `"explicit"` + - `"auto"` - - `ComputerScreenshotContent object { detail, file_id, image_url, 2 more }` + - `size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or "auto"` - A screenshot of a computer. + The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. - - `detail: "low" or "high" or "auto" or "original"` + - `string` - The detail level of the screenshot image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + - `"1024x1024" or "1024x1536" or "1536x1024" or "auto"` - - `"low"` + 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`. - - `"high"` + - `"1024x1024"` - - `"auto"` + - `"1024x1536"` - - `"original"` + - `"1536x1024"` - - `file_id: string` + - `"auto"` - The identifier of an uploaded file that contains the screenshot. + - `LocalShell object { type }` - - `image_url: string` + A tool that allows the model to execute shell commands in a local environment. - The URL of the screenshot image. + - `type: "local_shell"` - - `type: "computer_screenshot"` + The type of the local shell tool. Always `local_shell`. - Specifies the event type. For a computer screenshot, this property is always set to `computer_screenshot`. + - `"local_shell"` - - `"computer_screenshot"` + - `Shell object { type, allowed_callers, environment }` - - `prompt_cache_breakpoint: optional object { mode }` + A tool that allows the model to execute shell commands. - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + - `type: "shell"` - - `mode: "explicit"` + The type of the shell tool. Always `shell`. - The breakpoint mode. Always `explicit`. + - `"shell"` - - `"explicit"` + - `allowed_callers: optional array of "direct" or "programmatic"` - - `ResponseInputFile object { type, detail, file_data, 4 more }` + The tool invocation context(s). - A file input to the model. + - `"direct"` - - `type: "input_file"` + - `"programmatic"` - The type of the input item. Always `input_file`. + - `environment: optional ContainerAuto or LocalEnvironment or ContainerReference` - - `"input_file"` + - `ContainerAuto object { type, file_ids, memory_limit, 2 more }` - - `detail: optional "auto" or "low" or "high"` + - `LocalEnvironment object { type, skills }` - The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. + - `ContainerReference object { container_id, type }` - - `"auto"` + - `Custom object { name, type, allowed_callers, 3 more }` - - `"low"` + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) - - `"high"` + - `name: string` - - `file_data: optional string` + The name of the custom tool, used to identify it in tool calls. - The content of the file to be sent to the model. + - `type: "custom"` - - `file_id: optional string` + The type of the custom tool. Always `custom`. - The ID of the file to be sent to the model. + - `"custom"` - - `file_url: optional string` + - `allowed_callers: optional array of "direct" or "programmatic"` - The URL of the file to be sent to the model. + The tool invocation context(s). - - `filename: optional string` + - `"direct"` - The name of the file to be sent to the model. + - `"programmatic"` - - `prompt_cache_breakpoint: optional object { mode }` + - `defer_loading: optional boolean` - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + Whether this tool should be deferred and discovered via tool search. - - `mode: "explicit"` + - `description: optional string` - The breakpoint mode. Always `explicit`. + Optional description of the custom tool, used to provide more context. - - `"explicit"` + - `format: optional CustomToolInputFormat` - - `role: "unknown" or "user" or "assistant" or 5 more` + The input format for the custom tool. Default is unconstrained text. - The role of the message. One of `unknown`, `user`, `assistant`, `system`, `critic`, `discriminator`, `developer`, or `tool`. + - `Namespace object { description, name, tools, type }` - - `"unknown"` + Groups function/custom tools under a shared namespace. - - `"user"` + - `description: string` - - `"assistant"` + A description of the namespace shown to the model. - - `"system"` + - `name: string` - - `"critic"` + The namespace name used in tool calls (for example, `crm`). - - `"discriminator"` + - `tools: array of object { name, type, allowed_callers, 5 more } or object { name, type, allowed_callers, 3 more }` - - `"developer"` + The function/custom tools available inside this namespace. - - `"tool"` + - `Function object { name, type, allowed_callers, 5 more }` - - `status: "in_progress" or "completed" or "incomplete"` + - `name: string` - The status of item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. + - `type: "function"` - - `"in_progress"` + - `"function"` - - `"completed"` + - `allowed_callers: optional array of "direct" or "programmatic"` - - `"incomplete"` + The tool invocation context(s). - - `type: "message"` + - `"direct"` - The type of the message. Always set to `message`. + - `"programmatic"` - - `"message"` + - `defer_loading: optional boolean` - - `phase: optional "commentary" or "final_answer"` + Whether this function should be deferred and discovered via tool search. - 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. + - `description: optional string` - - `"commentary"` + - `output_schema: optional map[unknown]` - - `"final_answer"` + A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. - - `Program object { id, call_id, code, 2 more }` + - `parameters: optional unknown` - - `id: string` + - `strict: optional boolean` - The unique ID of the program item. + Whether to enforce strict parameter validation. If omitted, Responses attempts to use strict validation when the schema is compatible, and falls back to non-strict validation otherwise. - - `call_id: string` + - `Custom object { name, type, allowed_callers, 3 more }` - The stable call ID of the program item. + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) - - `code: string` + - `name: string` - The JavaScript source executed by programmatic tool calling. + The name of the custom tool, used to identify it in tool calls. - - `fingerprint: string` + - `type: "custom"` - Opaque program replay fingerprint that must be round-tripped. + The type of the custom tool. Always `custom`. - - `type: "program"` + - `"custom"` - The type of the item. Always `program`. + - `allowed_callers: optional array of "direct" or "programmatic"` - - `"program"` + The tool invocation context(s). - - `ProgramOutput object { id, call_id, result, 2 more }` + - `"direct"` - - `id: string` + - `"programmatic"` - The unique ID of the program output item. + - `defer_loading: optional boolean` - - `call_id: string` + Whether this tool should be deferred and discovered via tool search. - The call ID of the program item. + - `description: optional string` - - `result: string` + Optional description of the custom tool, used to provide more context. - The result produced by the program item. + - `format: optional CustomToolInputFormat` - - `status: "completed" or "incomplete"` + The input format for the custom tool. Default is unconstrained text. - The terminal status of the program output item. + - `type: "namespace"` - - `"completed"` + The type of the tool. Always `namespace`. - - `"incomplete"` + - `"namespace"` - - `type: "program_output"` + - `ToolSearch object { type, description, execution, parameters }` - The type of the item. Always `program_output`. + Hosted or BYOT tool search configuration for deferred tools. - - `"program_output"` + - `type: "tool_search"` - - `FunctionCall object { arguments, call_id, name, 5 more }` + The type of the tool. Always `tool_search`. - A tool call to run a function. See the - [function calling guide](/docs/guides/function-calling) for more information. + - `"tool_search"` - - `arguments: string` + - `description: optional string` - A JSON string of the arguments to pass to the function. + Description shown to the model for a client-executed tool search tool. - - `call_id: string` + - `execution: optional "server" or "client"` - The unique ID of the function tool call generated by the model. + Whether tool search is executed by the server or by the client. - - `name: string` + - `"server"` - The name of the function to run. + - `"client"` - - `type: "function_call"` + - `parameters: optional unknown` - The type of the function tool call. Always `function_call`. + Parameter schema for a client-executed tool search tool. - - `"function_call"` + - `WebSearchPreview object { type, search_content_types, search_context_size, user_location }` - - `id: optional 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 function tool call. + - `type: "web_search_preview" or "web_search_preview_2025_03_11"` - - `caller: optional object { type } or object { caller_id, type }` + The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. - The execution context that produced this tool call. + - `"web_search_preview"` - - `Direct object { type }` + - `"web_search_preview_2025_03_11"` - - `type: "direct"` + - `search_content_types: optional array of "text" or "image"` - - `"direct"` + - `"text"` - - `Program object { caller_id, type }` + - `"image"` - - `caller_id: string` + - `search_context_size: optional "low" or "medium" or "high"` - The call ID of the program item that produced this tool 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. - - `type: "program"` + - `"low"` - - `"program"` + - `"medium"` - - `namespace: optional string` + - `"high"` - The namespace of the function to run. + - `user_location: optional object { type, city, country, 2 more }` - - `status: optional "in_progress" or "completed" or "incomplete"` + The user's location. - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `type: "approximate"` - - `"in_progress"` + The type of location approximation. Always `approximate`. - - `"completed"` + - `"approximate"` - - `"incomplete"` + - `city: optional string` - - `ToolSearchCall object { id, arguments, call_id, 4 more }` + Free text input for the city of the user, e.g. `San Francisco`. - - `id: string` + - `country: optional string` - The unique ID of the tool search call item. + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - - `arguments: unknown` + - `region: optional string` - Arguments used for the tool search call. + Free text input for the region of the user, e.g. `California`. - - `call_id: string` + - `timezone: optional string` - The unique ID of the tool search call generated by the model. + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - - `execution: "server" or "client"` + - `ApplyPatch object { type, allowed_callers }` - Whether tool search was executed by the server or by the client. + Allows the assistant to create, delete, or update files using unified diffs. - - `"server"` + - `type: "apply_patch"` - - `"client"` + The type of the tool. Always `apply_patch`. - - `status: "in_progress" or "completed" or "incomplete"` + - `"apply_patch"` - The status of the tool search call item that was recorded. + - `allowed_callers: optional array of "direct" or "programmatic"` - - `"in_progress"` + The tool invocation context(s). - - `"completed"` + - `"direct"` - - `"incomplete"` + - `"programmatic"` - - `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, 5 more } or object { type, vector_store_ids, filters, 2 more } or object { type } or 13 more` - The loaded tool definitions returned by tool search. + The additional tool definitions made available at this item. - `Function object { name, parameters, strict, 5 more }` @@ -39262,77 +39372,10 @@ Learn when and how to compact long-running conversations in the [conversation st 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. @@ -39668,40 +39711,8 @@ Learn when and how to compact long-running conversations in the [conversation st - `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`. @@ -39882,128 +39893,10 @@ Learn when and how to compact long-running conversations in the [conversation st - `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, allowed_callers, 3 more }` A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) @@ -40038,38 +39931,6 @@ Learn when and how to compact long-running conversations in the [conversation st 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. @@ -40256,881 +40117,788 @@ Learn when and how to compact long-running conversations in the [conversation st - `"programmatic"` - - `type: "tool_search_output"` - - The type of the item. Always `tool_search_output`. + - `type: "additional_tools"` - - `"tool_search_output"` + The type of the item. Always `additional_tools`. - - `created_by: optional string` + - `"additional_tools"` - The identifier of the actor that created the item. + - `Compaction object { id, encrypted_content, type, created_by }` - - `AdditionalTools object { id, role, tools, type }` + A compaction item generated by the [`v1/responses/compact` API](/docs/api-reference/responses/compact). - `id: string` - The unique ID of the additional tools item. - - - `role: "unknown" or "user" or "assistant" or 5 more` - - The role that provided the additional tools. - - - `"unknown"` - - - `"user"` - - - `"assistant"` - - - `"system"` - - - `"critic"` - - - `"discriminator"` - - - `"developer"` - - - `"tool"` - - - `tools: array of object { name, parameters, strict, 5 more } or object { type, vector_store_ids, filters, 2 more } or object { type } or 13 more` - - The additional tool definitions made available at this item. - - - `Function object { name, parameters, strict, 5 more }` - - Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). - - - `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 strict parameter validation is enforced for this function tool. - - - `type: "function"` - - The type of the function tool. Always `function`. - - - `"function"` - - - `allowed_callers: optional array of "direct" or "programmatic"` - - The tool invocation context(s). - - - `"direct"` - - - `"programmatic"` - - - `defer_loading: optional boolean` - - Whether this function is deferred and loaded via tool search. - - - `description: optional string` - - A description of the function. Used by the model to determine whether or not to call the function. + The unique ID of the compaction item. - - `output_schema: optional map[unknown]` + - `encrypted_content: string` - A JSON schema object describing the JSON value encoded in string outputs for this function. + The encrypted content that was produced by compaction. - - `FileSearch object { type, vector_store_ids, filters, 2 more }` + - `type: "compaction"` - 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 type of the item. Always `compaction`. - - `type: "file_search"` + - `"compaction"` - The type of the file search tool. Always `file_search`. + - `created_by: optional string` - - `"file_search"` + The identifier of the actor that created the item. - - `vector_store_ids: array of string` + - `ImageGenerationCall object { id, result, status, type }` - The IDs of the vector stores to search. + An image generation request made by the model. - - `filters: optional ComparisonFilter or CompoundFilter` + - `id: string` - A filter to apply. + The unique ID of the image generation call. - - `ComparisonFilter object { key, type, value }` + - `result: string` - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + The generated image encoded in base64. - - `CompoundFilter object { filters, type }` + - `status: "in_progress" or "completed" or "generating" or "failed"` - Combine multiple filters using `and` or `or`. + The status of the image generation call. - - `max_num_results: optional number` + - `"in_progress"` - The maximum number of results to return. This number should be between 1 and 50 inclusive. + - `"completed"` - - `ranking_options: optional object { hybrid_search, ranker, score_threshold }` + - `"generating"` - Ranking options for search. + - `"failed"` - - `hybrid_search: optional object { embedding_weight, text_weight }` + - `type: "image_generation_call"` - Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. + The type of the image generation call. Always `image_generation_call`. - - `embedding_weight: number` + - `"image_generation_call"` - The weight of the embedding in the reciprocal ranking fusion. + - `CodeInterpreterCall object { id, code, container_id, 3 more }` - - `text_weight: number` + A tool call to run code. - The weight of the text in the reciprocal ranking fusion. + - `id: string` - - `ranker: optional "auto" or "default-2024-11-15"` + The unique ID of the code interpreter tool call. - The ranker to use for the file search. + - `code: string` - - `"auto"` + The code to run, or null if not available. - - `"default-2024-11-15"` + - `container_id: string` - - `score_threshold: optional number` + The ID of the container used to run the code. - 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. + - `outputs: array of object { logs, type } or object { type, url }` - - `Computer object { type }` + The outputs generated by the code interpreter, such as logs or images. + Can be null if no outputs are available. - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `Logs object { logs, type }` - - `type: "computer"` + The logs output from the code interpreter. - The type of the computer tool. Always `computer`. + - `logs: string` - - `"computer"` + The logs output from the code interpreter. - - `ComputerUsePreview object { display_height, display_width, environment, type }` + - `type: "logs"` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + The type of the output. Always `logs`. - - `display_height: number` + - `"logs"` - The height of the computer display. + - `Image object { type, url }` - - `display_width: number` + The image output from the code interpreter. - The width of the computer display. + - `type: "image"` - - `environment: "windows" or "mac" or "linux" or 2 more` + The type of the output. Always `image`. - The type of computer environment to control. + - `"image"` - - `"windows"` + - `url: string` - - `"mac"` + The URL of the image output from the code interpreter. - - `"linux"` + - `status: "in_progress" or "completed" or "incomplete" or 2 more` - - `"ubuntu"` + The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. - - `"browser"` + - `"in_progress"` - - `type: "computer_use_preview"` + - `"completed"` - The type of the computer use tool. Always `computer_use_preview`. + - `"incomplete"` - - `"computer_use_preview"` + - `"interpreting"` - - `WebSearch object { type, filters, search_context_size, user_location }` + - `"failed"` - Search the Internet for sources related to the prompt. Learn more about the - [web search tool](/docs/guides/tools-web-search). + - `type: "code_interpreter_call"` - - `type: "web_search" or "web_search_2025_08_26"` + The type of the code interpreter tool call. Always `code_interpreter_call`. - The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. + - `"code_interpreter_call"` - - `"web_search"` + - `LocalShellCall object { id, action, call_id, 2 more }` - - `"web_search_2025_08_26"` + A tool call to run a command on the local shell. - - `filters: optional object { allowed_domains }` + - `id: string` - Filters for the search. + The unique ID of the local shell call. - - `allowed_domains: optional array of string` + - `action: object { command, env, type, 3 more }` - Allowed domains for the search. If not provided, all domains are allowed. - Subdomains of the provided domains are allowed as well. + Execute a shell command on the server. - Example: `["pubmed.ncbi.nlm.nih.gov"]` + - `command: array of string` - - `search_context_size: optional "low" or "medium" or "high"` + The command to run. - 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. + - `env: map[string]` - - `"low"` + Environment variables to set for the command. - - `"medium"` + - `type: "exec"` - - `"high"` + The type of the local shell action. Always `exec`. - - `user_location: optional object { city, country, region, 2 more }` + - `"exec"` - The approximate location of the user. + - `timeout_ms: optional number` - - `city: optional string` + Optional timeout in milliseconds for the command. - Free text input for the city of the user, e.g. `San Francisco`. + - `user: optional string` - - `country: optional string` + Optional user to run the command as. - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + - `working_directory: optional string` - - `region: optional string` + Optional working directory to run the command in. - Free text input for the region of the user, e.g. `California`. + - `call_id: string` - - `timezone: optional string` + The unique ID of the local shell tool call generated by the model. - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + - `status: "in_progress" or "completed" or "incomplete"` - - `type: optional "approximate"` + The status of the local shell call. - The type of location approximation. Always `approximate`. + - `"in_progress"` - - `"approximate"` + - `"completed"` - - `Mcp object { server_label, type, allowed_callers, 9 more }` + - `"incomplete"` - Give the model access to additional tools via remote Model Context Protocol - (MCP) servers. [Learn more about MCP](/docs/guides/tools-remote-mcp). + - `type: "local_shell_call"` - - `server_label: string` + The type of the local shell call. Always `local_shell_call`. - A label for this MCP server, used to identify it in tool calls. + - `"local_shell_call"` - - `type: "mcp"` + - `LocalShellCallOutput object { id, output, type, status }` - The type of the MCP tool. Always `mcp`. + The output of a local shell tool call. - - `"mcp"` + - `id: string` - - `allowed_callers: optional array of "direct" or "programmatic"` + The unique ID of the local shell tool call generated by the model. - The tool invocation context(s). + - `output: string` - - `"direct"` + A JSON string of the output of the local shell tool call. - - `"programmatic"` + - `type: "local_shell_call_output"` - - `allowed_tools: optional array of string or object { read_only, tool_names }` + The type of the local shell tool call output. Always `local_shell_call_output`. - List of allowed tool names or a filter object. + - `"local_shell_call_output"` - - `McpAllowedTools = array of string` + - `status: optional "in_progress" or "completed" or "incomplete"` - A string array of allowed tool names + The status of the item. One of `in_progress`, `completed`, or `incomplete`. - - `McpToolFilter object { read_only, tool_names }` + - `"in_progress"` - A filter object to specify which tools are allowed. + - `"completed"` - - `read_only: optional boolean` + - `"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. + - `ShellCall object { id, action, call_id, 5 more }` - - `tool_names: optional array of string` + A tool call that executes one or more shell commands in a managed environment. - List of allowed tool names. + - `id: string` - - `authorization: optional string` + The unique ID of the shell tool call. 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. + - `action: object { commands, max_output_length, timeout_ms }` - - `connector_id: optional "connector_dropbox" or "connector_gmail" or "connector_googlecalendar" or 5 more` + The shell commands and limits that describe how to run the tool call. - Identifier for service connectors, like those available in ChatGPT. One of - `server_url`, `connector_id`, or `tunnel_id` must be provided. Learn more - about service connectors [here](/docs/guides/tools-remote-mcp#connectors). + - `commands: array of string` - Currently supported `connector_id` values are: + - `max_output_length: number` - - Dropbox: `connector_dropbox` - - Gmail: `connector_gmail` - - Google Calendar: `connector_googlecalendar` - - Google Drive: `connector_googledrive` - - Microsoft Teams: `connector_microsoftteams` - - Outlook Calendar: `connector_outlookcalendar` - - Outlook Email: `connector_outlookemail` - - SharePoint: `connector_sharepoint` + Optional maximum number of characters to return from each command. - - `"connector_dropbox"` + - `timeout_ms: number` - - `"connector_gmail"` + Optional timeout in milliseconds for the commands. - - `"connector_googlecalendar"` + - `call_id: string` - - `"connector_googledrive"` + The unique ID of the shell tool call generated by the model. - - `"connector_microsoftteams"` + - `environment: ResponseLocalEnvironment or ResponseContainerReference` - - `"connector_outlookcalendar"` + Represents the use of a local environment to perform shell actions. - - `"connector_outlookemail"` + - `ResponseLocalEnvironment object { type }` - - `"connector_sharepoint"` + Represents the use of a local environment to perform shell actions. - - `defer_loading: optional boolean` + - `type: "local"` - Whether this MCP tool is deferred and discovered via tool search. + The environment type. Always `local`. - - `headers: optional map[string]` + - `"local"` - Optional HTTP headers to send to the MCP server. Use for authentication - or other purposes. + - `ResponseContainerReference object { container_id, type }` - - `require_approval: optional object { always, never } or "always" or "never"` + Represents a container created with /v1/containers. - Specify which of the MCP server's tools require approval. + - `container_id: string` - - `McpToolApprovalFilter object { always, never }` + - `type: "container_reference"` - 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 environment type. Always `container_reference`. - - `always: optional object { read_only, tool_names }` + - `"container_reference"` - A filter object to specify which tools are allowed. + - `status: "in_progress" or "completed" or "incomplete"` - - `read_only: optional boolean` + The status of the shell call. One of `in_progress`, `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. + - `"in_progress"` - - `tool_names: optional array of string` + - `"completed"` - List of allowed tool names. + - `"incomplete"` - - `never: 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. + - `caller: optional object { type } or object { caller_id, type }` - - `tool_names: optional array of string` + The execution context that produced this tool call. - List of allowed tool names. + - `Direct object { type }` - - `McpToolApprovalSetting = "always" or "never"` + - `type: "direct"` - 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. + - `"direct"` - - `"always"` + - `Program object { caller_id, type }` - - `"never"` + - `caller_id: string` - - `server_description: optional string` + The call ID of the program item that produced this tool call. - Optional description of the MCP server, used to provide more context. + - `type: "program"` - - `server_url: optional string` + - `"program"` - The URL for the MCP server. One of `server_url`, `connector_id`, or - `tunnel_id` must be provided. + - `created_by: optional string` - - `tunnel_id: optional string` + The ID of the entity that created this tool call. - The Secure MCP Tunnel ID to use instead of a direct server URL. One of - `server_url`, `connector_id`, or `tunnel_id` must be provided. + - `ShellCallOutput object { id, call_id, max_output_length, 5 more }` - - `CodeInterpreter object { container, type, allowed_callers }` + The output of a shell tool call that was emitted. - A tool that runs Python code to help generate a response to a prompt. + - `id: string` - - `container: string or object { type, file_ids, memory_limit, network_policy }` + The unique ID of the shell call output. Populated when this item is 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. + - `call_id: string` - - `string` + The unique ID of the shell tool call generated by the model. - The container ID. + - `max_output_length: number` - - `CodeInterpreterToolAuto object { type, file_ids, memory_limit, network_policy }` + The maximum length of the shell command output. This is generated by the model and should be passed back with the raw output. - Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. + - `output: array of object { outcome, stderr, stdout, created_by }` - - `type: "auto"` + An array of shell call output contents - Always `auto`. + - `outcome: object { type } or object { exit_code, type }` - - `"auto"` + Represents either an exit outcome (with an exit code) or a timeout outcome for a shell call output chunk. - - `file_ids: optional array of string` + - `Timeout object { type }` - An optional list of uploaded files to make available to your code. + Indicates that the shell call exceeded its configured time limit. - - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` + - `type: "timeout"` - The memory limit for the code interpreter container. + The outcome type. Always `timeout`. - - `"1g"` + - `"timeout"` - - `"4g"` + - `Exit object { exit_code, type }` - - `"16g"` + Indicates that the shell commands finished and returned an exit code. - - `"64g"` + - `exit_code: number` - - `network_policy: optional ContainerNetworkPolicyDisabled or ContainerNetworkPolicyAllowlist` + Exit code from the shell process. - Network access policy for the container. + - `type: "exit"` - - `ContainerNetworkPolicyDisabled object { type }` + The outcome type. Always `exit`. - - `ContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` + - `"exit"` - - `type: "code_interpreter"` + - `stderr: string` - The type of the code interpreter tool. Always `code_interpreter`. + The standard error output that was captured. - - `"code_interpreter"` + - `stdout: string` - - `allowed_callers: optional array of "direct" or "programmatic"` + The standard output that was captured. - The tool invocation context(s). + - `created_by: optional string` - - `"direct"` + The identifier of the actor that created the item. - - `"programmatic"` + - `status: "in_progress" or "completed" or "incomplete"` - - `ProgrammaticToolCalling object { type }` + The status of the shell call output. One of `in_progress`, `completed`, or `incomplete`. - - `type: "programmatic_tool_calling"` + - `"in_progress"` - The type of the tool. Always `programmatic_tool_calling`. + - `"completed"` - - `"programmatic_tool_calling"` + - `"incomplete"` - - `ImageGeneration object { type, action, background, 9 more }` + - `type: "shell_call_output"` - A tool that generates images using the GPT image models. + The type of the shell call output. Always `shell_call_output`. - - `type: "image_generation"` + - `"shell_call_output"` - The type of the image generation tool. Always `image_generation`. + - `caller: optional object { type } or object { caller_id, type }` - - `"image_generation"` + The execution context that produced this tool call. - - `action: optional "generate" or "edit" or "auto"` + - `Direct object { type }` - Whether to generate a new image or edit an existing image. Default: `auto`. + - `type: "direct"` - - `"generate"` + - `"direct"` - - `"edit"` + - `Program object { caller_id, type }` - - `"auto"` + - `caller_id: string` - - `background: optional "transparent" or "opaque" or "auto"` + The call ID of the program item that produced this tool call. - Background type for the generated image. One of `transparent`, - `opaque`, or `auto`. Default: `auto`. + - `type: "program"` - - `"transparent"` + - `"program"` - - `"opaque"` + - `created_by: optional string` - - `"auto"` + The identifier of the actor that created the item. - - `input_fidelity: optional "high" or "low"` + - `ApplyPatchCall object { id, call_id, operation, 4 more }` - 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`. + A tool call that applies file diffs by creating, deleting, or updating files. - - `"high"` + - `id: string` - - `"low"` + The unique ID of the apply patch tool call. Populated when this item is returned via API. - - `input_image_mask: optional object { file_id, image_url }` + - `call_id: string` - Optional mask for inpainting. Contains `image_url` - (string, optional) and `file_id` (string, optional). + The unique ID of the apply patch tool call generated by the model. - - `file_id: optional string` + - `operation: object { diff, path, type } or object { path, type } or object { diff, path, type }` - File ID for the mask image. + One of the create_file, delete_file, or update_file operations applied via apply_patch. - - `image_url: optional string` + - `CreateFile object { diff, path, type }` - Base64-encoded mask image. + Instruction describing how to create a file via the apply_patch tool. - - `model: optional string or "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`. + Diff to apply. - - `string` + - `path: string` - - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` + Path of the file to create. - The image generation model to use. Default: `gpt-image-1`. + - `type: "create_file"` - - `"gpt-image-1"` + Create a new file with the provided diff. - - `"gpt-image-1-mini"` + - `"create_file"` - - `"gpt-image-1.5"` + - `DeleteFile object { path, type }` - - `moderation: optional "auto" or "low"` + Instruction describing how to delete a file via the apply_patch tool. - Moderation level for the generated image. Default: `auto`. + - `path: string` - - `"auto"` + Path of the file to delete. - - `"low"` + - `type: "delete_file"` - - `output_compression: optional number` + Delete the specified file. - Compression level for the output image. Default: 100. + - `"delete_file"` - - `output_format: optional "png" or "webp" or "jpeg"` + - `UpdateFile object { diff, path, type }` - The output format of the generated image. One of `png`, `webp`, or - `jpeg`. Default: `png`. + Instruction describing how to update a file via the apply_patch tool. - - `"png"` + - `diff: string` - - `"webp"` + Diff to apply. - - `"jpeg"` + - `path: string` - - `partial_images: optional number` + Path of the file to update. - Number of partial images to generate in streaming mode, from 0 (default value) to 3. + - `type: "update_file"` - - `quality: optional "low" or "medium" or "high" or "auto"` + Update an existing file with the provided diff. - The quality of the generated image. One of `low`, `medium`, `high`, - or `auto`. Default: `auto`. + - `"update_file"` - - `"low"` + - `status: "in_progress" or "completed"` - - `"medium"` + The status of the apply patch tool call. One of `in_progress` or `completed`. - - `"high"` + - `"in_progress"` - - `"auto"` + - `"completed"` - - `size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or "auto"` + - `type: "apply_patch_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`. + The type of the item. Always `apply_patch_call`. - - `string` + - `"apply_patch_call"` - - `"1024x1024" or "1024x1536" or "1536x1024" or "auto"` + - `caller: optional object { type } or object { caller_id, 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 execution context that produced this tool call. - - `"1024x1024"` + - `Direct object { type }` - - `"1024x1536"` + - `type: "direct"` - - `"1536x1024"` + - `"direct"` - - `"auto"` + - `Program object { caller_id, type }` - - `LocalShell object { type }` + - `caller_id: string` - A tool that allows the model to execute shell commands in a local environment. + The call ID of the program item that produced this tool call. - - `type: "local_shell"` + - `type: "program"` - The type of the local shell tool. Always `local_shell`. + - `"program"` - - `"local_shell"` + - `created_by: optional string` - - `Shell object { type, allowed_callers, environment }` + The ID of the entity that created this tool call. - A tool that allows the model to execute shell commands. + - `ApplyPatchCallOutput object { id, call_id, status, 4 more }` - - `type: "shell"` + The output emitted by an apply patch tool call. - The type of the shell tool. Always `shell`. + - `id: string` - - `"shell"` + The unique ID of the apply patch tool call output. Populated when this item is returned via API. - - `allowed_callers: optional array of "direct" or "programmatic"` + - `call_id: string` - The tool invocation context(s). + The unique ID of the apply patch tool call generated by the model. - - `"direct"` + - `status: "completed" or "failed"` - - `"programmatic"` + The status of the apply patch tool call output. One of `completed` or `failed`. - - `environment: optional ContainerAuto or LocalEnvironment or ContainerReference` + - `"completed"` - - `ContainerAuto object { type, file_ids, memory_limit, 2 more }` + - `"failed"` - - `LocalEnvironment object { type, skills }` + - `type: "apply_patch_call_output"` - - `ContainerReference object { container_id, type }` + The type of the item. Always `apply_patch_call_output`. - - `Custom object { name, type, allowed_callers, 3 more }` + - `"apply_patch_call_output"` - A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) + - `caller: optional object { type } or object { caller_id, type }` - - `name: string` + The execution context that produced this tool call. - The name of the custom tool, used to identify it in tool calls. + - `Direct object { type }` - - `type: "custom"` + - `type: "direct"` - The type of the custom tool. Always `custom`. + - `"direct"` - - `"custom"` + - `Program object { caller_id, type }` - - `allowed_callers: optional array of "direct" or "programmatic"` + - `caller_id: string` - The tool invocation context(s). + The call ID of the program item that produced this tool call. - - `"direct"` + - `type: "program"` - - `"programmatic"` + - `"program"` - - `defer_loading: optional boolean` + - `created_by: optional string` - Whether this tool should be deferred and discovered via tool search. + The ID of the entity that created this tool call output. - - `description: optional string` + - `output: optional string` - Optional description of the custom tool, used to provide more context. + Optional textual output returned by the apply patch tool. - - `format: optional CustomToolInputFormat` + - `McpCall object { id, arguments, name, 6 more }` - The input format for the custom tool. Default is unconstrained text. + An invocation of a tool on an MCP server. - - `Namespace object { description, name, tools, type }` + - `id: string` - Groups function/custom tools under a shared namespace. + The unique ID of the tool call. - - `description: string` + - `arguments: string` - A description of the namespace shown to the model. + A JSON string of the arguments passed to the tool. - `name: string` - The namespace name used in tool calls (for example, `crm`). + The name of the tool that was run. - - `tools: array of object { name, type, allowed_callers, 5 more } or object { name, type, allowed_callers, 3 more }` + - `server_label: string` - The function/custom tools available inside this namespace. + The label of the MCP server running the tool. - - `Function object { name, type, allowed_callers, 5 more }` + - `type: "mcp_call"` - - `name: string` + The type of the item. Always `mcp_call`. - - `type: "function"` + - `"mcp_call"` - - `"function"` + - `approval_request_id: optional string` - - `allowed_callers: optional array of "direct" or "programmatic"` + 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. - The tool invocation context(s). + - `error: optional string` - - `"direct"` + The error from the tool call, if any. - - `"programmatic"` + - `output: optional string` - - `defer_loading: optional boolean` + The output from the tool call. - Whether this function should be deferred and discovered via 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`. - - `output_schema: optional map[unknown]` + - `"in_progress"` - A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. + - `"completed"` - - `parameters: optional unknown` + - `"incomplete"` - - `strict: optional boolean` + - `"calling"` - Whether to enforce strict parameter validation. If omitted, Responses attempts to use strict validation when the schema is compatible, and falls back to non-strict validation otherwise. + - `"failed"` - - `Custom object { name, type, allowed_callers, 3 more }` + - `McpListTools object { id, server_label, tools, 2 more }` - A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) + A list of tools available on an MCP server. - - `name: string` + - `id: string` - The name of the custom tool, used to identify it in tool calls. + The unique ID of the list. - - `type: "custom"` + - `server_label: string` - The type of the custom tool. Always `custom`. + The label of the MCP server. - - `"custom"` + - `tools: array of object { input_schema, name, annotations, description }` - - `allowed_callers: optional array of "direct" or "programmatic"` + The tools available on the server. - The tool invocation context(s). + - `input_schema: unknown` - - `"direct"` + The JSON schema describing the tool's input. - - `"programmatic"` + - `name: string` - - `defer_loading: optional boolean` + The name of the tool. - Whether this tool should be deferred and discovered via tool search. + - `annotations: optional unknown` + + Additional annotations about the tool. - `description: optional string` - Optional description of the custom tool, used to provide more context. + The description of the tool. - - `format: optional CustomToolInputFormat` + - `type: "mcp_list_tools"` - The input format for the custom tool. Default is unconstrained text. + The type of the item. Always `mcp_list_tools`. - - `type: "namespace"` + - `"mcp_list_tools"` - The type of the tool. Always `namespace`. + - `error: optional string` - - `"namespace"` + Error message if the server could not list tools. - - `ToolSearch object { type, description, execution, parameters }` + - `McpApprovalRequest object { id, arguments, name, 2 more }` - Hosted or BYOT tool search configuration for deferred tools. + A request for human approval of a tool invocation. - - `type: "tool_search"` + - `id: string` - The type of the tool. Always `tool_search`. + The unique ID of the approval request. - - `"tool_search"` + - `arguments: string` - - `description: optional string` + A JSON string of arguments for the tool. - Description shown to the model for a client-executed tool search tool. + - `name: string` - - `execution: optional "server" or "client"` + The name of the tool to run. - Whether tool search is executed by the server or by the client. + - `server_label: string` - - `"server"` + The label of the MCP server making the request. - - `"client"` + - `type: "mcp_approval_request"` - - `parameters: optional unknown` + The type of the item. Always `mcp_approval_request`. - Parameter schema for a client-executed tool search tool. + - `"mcp_approval_request"` - - `WebSearchPreview object { type, search_content_types, search_context_size, user_location }` + - `McpApprovalResponse object { id, approval_request_id, approve, 2 more }` - 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 response to an MCP approval request. - - `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 unique ID of the approval response - - `"web_search_preview"` + - `approval_request_id: string` - - `"web_search_preview_2025_03_11"` + The ID of the approval request being answered. - - `search_content_types: optional array of "text" or "image"` + - `approve: boolean` - - `"text"` + Whether the request was approved. - - `"image"` + - `type: "mcp_approval_response"` - - `search_context_size: optional "low" or "medium" or "high"` + The type of the item. Always `mcp_approval_response`. - 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. + - `"mcp_approval_response"` - - `"low"` + - `reason: optional string` - - `"medium"` + Optional reason for the decision. - - `"high"` + - `CustomToolCall object { call_id, input, name, 4 more }` - - `user_location: optional object { type, city, country, 2 more }` + A call to a custom tool created by the model. - The user's location. + - `call_id: string` - - `type: "approximate"` + An identifier used to map this custom tool call to a tool call output. - The type of location approximation. Always `approximate`. + - `input: string` - - `"approximate"` + The input for the custom tool call generated by the model. - - `city: optional string` + - `name: string` - Free text input for the city of the user, e.g. `San Francisco`. + The name of the custom tool being called. - - `country: optional string` + - `type: "custom_tool_call"` - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + The type of the custom tool call. Always `custom_tool_call`. - - `region: optional string` + - `"custom_tool_call"` - Free text input for the region of the user, e.g. `California`. + - `id: optional string` - - `timezone: optional string` + The unique ID of the custom tool call in the OpenAI platform. - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + - `caller: optional object { type } or object { caller_id, type }` - - `ApplyPatch object { type, allowed_callers }` + The execution context that produced this tool call. - Allows the assistant to create, delete, or update files using unified diffs. + - `Direct object { type }` - - `type: "apply_patch"` + - `type: "direct"` - The type of the tool. Always `apply_patch`. + - `"direct"` - - `"apply_patch"` + - `Program object { caller_id, type }` - - `allowed_callers: optional array of "direct" or "programmatic"` + - `caller_id: string` - The tool invocation context(s). + The call ID of the program item that produced this tool call. - - `"direct"` + - `type: "program"` - - `"programmatic"` + - `"program"` - - `type: "additional_tools"` + - `namespace: optional string` - The type of the item. Always `additional_tools`. + The namespace of the custom tool being called. - - `"additional_tools"` + - `CustomToolCallOutput object { id, call_id, output, 4 more }` - - `FunctionCallOutput object { call_id, output, type, 3 more }` + - `id: string` - The output of a function tool call. + The unique ID of the custom tool call output item. - `call_id: string` - The unique ID of the function tool call generated by the model. + 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 function call generated by your code. + 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 function call. + 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 function call. + Text, image, or file output of the custom tool call. - `ResponseInputText object { text, type, prompt_cache_breakpoint }` @@ -41144,16 +40912,22 @@ Learn when and how to compact long-running conversations in the [conversation st A file input to the model. - - `type: "function_call_output"` + - `status: "in_progress" or "completed" or "incomplete"` - The type of the function tool call output. Always `function_call_output`. + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `"function_call_output"` + - `"in_progress"` - - `id: optional string` + - `"completed"` - The unique ID of the function tool call output. Populated when this item - is returned via API. + - `"incomplete"` + + - `type: "custom_tool_call_output"` + + The type of the custom tool call output. Always `custom_tool_call_output`. + + - `"custom_tool_call_output"` - `caller: optional object { type } or object { caller_id, type }` @@ -41179,1416 +40953,1510 @@ Learn when and how to compact long-running conversations in the [conversation st - `"program"` - - `status: optional "in_progress" or "completed" or "incomplete"` - - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. - - - `"in_progress"` - - - `"completed"` - - - `"incomplete"` - - - `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` + - `created_by: optional string` - The unique ID of the file search tool call. + The identifier of the actor that created the item. - - `queries: array of string` + - `parallel_tool_calls: boolean` - The queries used to search for files. + Whether to allow the model to run tool calls in parallel. - - `status: "in_progress" or "searching" or "completed" or 2 more` + - `temperature: number` - The status of the file search tool call. One of `in_progress`, - `searching`, `incomplete` or `failed`, + What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. + We generally recommend altering this or `top_p` but not both. - - `"in_progress"` + - `tool_choice: ToolChoiceOptions or ToolChoiceAllowed or ToolChoiceTypes or 6 more` - - `"searching"` + How the model should select which tool (or tools) to use when generating + a response. See the `tools` parameter to see how to specify which tools + the model can call. - - `"completed"` + - `ToolChoiceOptions = "none" or "auto" or "required"` - - `"incomplete"` + Controls which (if any) tool is called by the model. - - `"failed"` + `none` means the model will not call any tool and instead generates a message. - - `type: "file_search_call"` + `auto` means the model can pick between generating a message or calling one or + more tools. - The type of the file search tool call. Always `file_search_call`. + `required` means the model must call one or more tools. - - `"file_search_call"` + - `"none"` - - `results: optional array of object { attributes, file_id, filename, 2 more }` + - `"auto"` - The results of the file search tool call. + - `"required"` - - `attributes: optional map[string or number or boolean]` + - `ToolChoiceAllowed object { mode, tools, type }` - 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. + Constrains the tools available to the model to a pre-defined set. - - `string` + - `mode: "auto" or "required"` - - `number` + Constrains the tools available to the model to a pre-defined set. - - `boolean` + `auto` allows the model to pick from among the allowed tools and generate a + message. - - `file_id: optional string` + `required` requires the model to call one or more of the allowed tools. - The unique ID of the file. + - `"auto"` - - `filename: optional string` + - `"required"` - The name of the file. + - `tools: array of map[unknown]` - - `score: optional number` + A list of tool definitions that the model should be allowed to call. - The relevance score of the file - a value between 0 and 1. + For the Responses API, the list of tool definitions might look like: - - `text: optional string` + ```json + [ + { "type": "function", "name": "get_weather" }, + { "type": "mcp", "server_label": "deepwiki" }, + { "type": "image_generation" } + ] + ``` - The text that was retrieved from the file. + - `type: "allowed_tools"` - - `WebSearchCall object { id, action, status, type }` + Allowed tool configuration type. Always `allowed_tools`. - The results of a web search tool call. See the - [web search guide](/docs/guides/tools-web-search) for more information. + - `"allowed_tools"` - - `id: string` + - `ToolChoiceTypes object { type }` - The unique ID of the web search tool call. + Indicates that the model should use a built-in tool to generate a response. + [Learn more about built-in tools](/docs/guides/tools). - - `action: object { type, queries, query, sources } or object { type, url } or object { pattern, type, url }` + - `type: "file_search" or "web_search_preview" or "computer" or 5 more` - 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 hosted tool the model should to use. Learn more about + [built-in tools](/docs/guides/tools). - - `Search object { type, queries, query, sources }` + Allowed values are: - Action type "search" - Performs a web search query. + - `file_search` + - `web_search_preview` + - `computer` + - `computer_use_preview` + - `computer_use` + - `code_interpreter` + - `image_generation` - - `type: "search"` + - `"file_search"` - The action type. + - `"web_search_preview"` - - `"search"` + - `"computer"` - - `queries: optional array of string` + - `"computer_use_preview"` - The search queries. + - `"computer_use"` - - `query: optional string` + - `"web_search_preview_2025_03_11"` - The search query. + - `"image_generation"` - - `sources: optional array of object { type, url }` + - `"code_interpreter"` - The sources used in the search. + - `ToolChoiceFunction object { name, type }` - - `type: "url"` + Use this option to force the model to call a specific function. - The type of source. Always `url`. + - `name: string` - - `"url"` + The name of the function to call. - - `url: string` + - `type: "function"` - The URL of the source. + For function calling, the type is always `function`. - - `OpenPage object { type, url }` + - `"function"` - Action type "open_page" - Opens a specific URL from search results. + - `ToolChoiceMcp object { server_label, type, name }` - - `type: "open_page"` + Use this option to force the model to call a specific tool on a remote MCP server. - The action type. + - `server_label: string` - - `"open_page"` + The label of the MCP server to use. - - `url: optional string` + - `type: "mcp"` - The URL opened by the model. + For MCP tools, the type is always `mcp`. - - `FindInPage object { pattern, type, url }` + - `"mcp"` - Action type "find_in_page": Searches for a pattern within a loaded page. + - `name: optional string` - - `pattern: string` + The name of the tool to call on the server. - The pattern or text to search for within the page. + - `ToolChoiceCustom object { name, type }` - - `type: "find_in_page"` + Use this option to force the model to call a specific custom tool. - The action type. + - `name: string` - - `"find_in_page"` + The name of the custom tool to call. - - `url: string` + - `type: "custom"` - The URL of the page searched for the pattern. + For custom tool calling, the type is always `custom`. - - `status: "in_progress" or "searching" or "completed" or "failed"` + - `"custom"` - The status of the web search tool call. + - `SpecificProgrammaticToolCallingParam object { type }` - - `"in_progress"` + - `type: "programmatic_tool_calling"` - - `"searching"` + The tool to call. Always `programmatic_tool_calling`. - - `"completed"` + - `"programmatic_tool_calling"` - - `"failed"` + - `ToolChoiceApplyPatch object { type }` - - `type: "web_search_call"` + Forces the model to call the apply_patch tool when executing a tool call. - The type of the web search tool call. Always `web_search_call`. + - `type: "apply_patch"` - - `"web_search_call"` + The tool to call. Always `apply_patch`. - - `ImageGenerationCall object { id, result, status, type }` + - `"apply_patch"` - An image generation request made by the model. + - `ToolChoiceShell object { type }` - - `id: string` + Forces the model to call the shell tool when a tool call is required. - The unique ID of the image generation call. + - `type: "shell"` - - `result: string` + The tool to call. Always `shell`. - The generated image encoded in base64. + - `"shell"` - - `status: "in_progress" or "completed" or "generating" or "failed"` + - `tools: array of object { name, parameters, strict, 5 more } or object { type, vector_store_ids, filters, 2 more } or object { type } or 13 more` - The status of the image generation call. + An array of tools the model may call while generating a response. You + can specify which tool to use by setting the `tool_choice` parameter. - - `"in_progress"` + We support the following categories of tools: - - `"completed"` + - **Built-in tools**: Tools that are provided by OpenAI that extend the + model's capabilities, like [web search](/docs/guides/tools-web-search) + or [file search](/docs/guides/tools-file-search). Learn more about + [built-in tools](/docs/guides/tools). + - **MCP Tools**: Integrations with third-party systems via custom MCP servers + or predefined connectors such as Google Drive and SharePoint. Learn more about + [MCP Tools](/docs/guides/tools-connectors-mcp). + - **Function calls (custom tools)**: Functions that are defined by you, + enabling the model to call your own code with strongly typed arguments + and outputs. Learn more about + [function calling](/docs/guides/function-calling). You can also use + custom tools to call your own code. - - `"generating"` + - `Function object { name, parameters, strict, 5 more }` - - `"failed"` + Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). - - `type: "image_generation_call"` + - `name: string` - The type of the image generation call. Always `image_generation_call`. + The name of the function to call. - - `"image_generation_call"` + - `parameters: map[unknown]` - - `ComputerCall object { id, call_id, pending_safety_checks, 4 more }` + A JSON schema object describing the parameters of the function. - A tool call to a computer use tool. See the - [computer use guide](/docs/guides/tools-computer-use) for more information. + - `strict: boolean` - - `id: string` + Whether strict parameter validation is enforced for this function tool. - The unique ID of the computer call. + - `type: "function"` - - `call_id: string` + The type of the function tool. Always `function`. - An identifier used when responding to the tool call with output. + - `"function"` - - `pending_safety_checks: array of object { id, code, message }` + - `allowed_callers: optional array of "direct" or "programmatic"` - The pending safety checks for the computer call. + The tool invocation context(s). - - `id: string` + - `"direct"` - The ID of the pending safety check. + - `"programmatic"` - - `code: optional string` + - `defer_loading: optional boolean` - The type of the pending safety check. + Whether this function is deferred and loaded via tool search. - - `message: optional string` + - `description: optional string` - Details about the pending safety check. + A description of the function. Used by the model to determine whether or not to call the function. - - `status: "in_progress" or "completed" or "incomplete"` + - `output_schema: optional map[unknown]` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + A JSON schema object describing the JSON value encoded in string outputs for this function. - - `"in_progress"` + - `FileSearch object { type, vector_store_ids, filters, 2 more }` - - `"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). - - `"incomplete"` + - `type: "file_search"` - - `type: "computer_call"` + The type of the file search tool. Always `file_search`. - The type of the computer call. Always `computer_call`. + - `"file_search"` - - `"computer_call"` + - `vector_store_ids: array of string` - - `action: optional ComputerAction` + The IDs of the vector stores to search. - A click action. + - `filters: optional ComparisonFilter or CompoundFilter` - - `Click object { button, type, x, 2 more }` + A filter to apply. - A click action. + - `ComparisonFilter object { key, type, value }` - - `button: "left" or "right" or "wheel" or 2 more` + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. + - `CompoundFilter object { filters, type }` - - `"left"` + Combine multiple filters using `and` or `or`. - - `"right"` + - `max_num_results: optional number` - - `"wheel"` + The maximum number of results to return. This number should be between 1 and 50 inclusive. - - `"back"` + - `ranking_options: optional object { hybrid_search, ranker, score_threshold }` - - `"forward"` + Ranking options for search. - - `type: "click"` + - `hybrid_search: optional object { embedding_weight, text_weight }` - Specifies the event type. For a click action, this property is always `click`. + Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. - - `"click"` + - `embedding_weight: number` - - `x: number` + The weight of the embedding in the reciprocal ranking fusion. - The x-coordinate where the click occurred. + - `text_weight: number` - - `y: number` + The weight of the text in the reciprocal ranking fusion. - The y-coordinate where the click occurred. + - `ranker: optional "auto" or "default-2024-11-15"` - - `keys: optional array of string` + The ranker to use for the file search. - The keys being held while clicking. + - `"auto"` - - `DoubleClick object { keys, type, x, y }` + - `"default-2024-11-15"` - A double click action. + - `score_threshold: optional number` - - `keys: array of 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 keys being held while double-clicking. + - `Computer object { type }` - - `type: "double_click"` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - Specifies the event type. For a double click action, this property is always set to `double_click`. + - `type: "computer"` - - `"double_click"` + The type of the computer tool. Always `computer`. - - `x: number` + - `"computer"` - The x-coordinate where the double click occurred. + - `ComputerUsePreview object { display_height, display_width, environment, type }` - - `y: number` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - The y-coordinate where the double click occurred. + - `display_height: number` - - `Drag object { path, type, keys }` + The height of the computer display. - A drag action. + - `display_width: number` - - `path: array of object { x, y }` + The width of the computer display. - An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg + - `environment: "windows" or "mac" or "linux" or 2 more` - ``` - [ - { x: 100, y: 200 }, - { x: 200, y: 300 } - ] - ``` + The type of computer environment to control. - - `x: number` + - `"windows"` - The x-coordinate. + - `"mac"` - - `y: number` + - `"linux"` - The y-coordinate. + - `"ubuntu"` - - `type: "drag"` + - `"browser"` - Specifies the event type. For a drag action, this property is always set to `drag`. + - `type: "computer_use_preview"` - - `"drag"` + The type of the computer use tool. Always `computer_use_preview`. - - `keys: optional array of string` + - `"computer_use_preview"` - The keys being held while dragging the mouse. + - `WebSearch object { type, filters, search_context_size, user_location }` - - `Keypress object { keys, type }` + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](/docs/guides/tools-web-search). - A collection of keypresses the model would like to perform. + - `type: "web_search" or "web_search_2025_08_26"` - - `keys: array of string` + The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. - The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. + - `"web_search"` - - `type: "keypress"` + - `"web_search_2025_08_26"` - Specifies the event type. For a keypress action, this property is always set to `keypress`. + - `filters: optional object { allowed_domains }` - - `"keypress"` + Filters for the search. - - `Move object { type, x, y, keys }` + - `allowed_domains: optional array of string` - A mouse move action. + Allowed domains for the search. If not provided, all domains are allowed. + Subdomains of the provided domains are allowed as well. - - `type: "move"` + Example: `["pubmed.ncbi.nlm.nih.gov"]` - Specifies the event type. For a move action, this property is always set to `move`. + - `search_context_size: optional "low" or "medium" or "high"` - - `"move"` + 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. - - `x: number` + - `"low"` - The x-coordinate to move to. + - `"medium"` - - `y: number` + - `"high"` - The y-coordinate to move to. + - `user_location: optional object { city, country, region, 2 more }` - - `keys: optional array of string` + The approximate location of the user. - The keys being held while moving the mouse. + - `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` - - `type: "screenshot"` + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - Specifies the event type. For a screenshot action, this property is always set to `screenshot`. + - `region: optional string` - - `"screenshot"` + Free text input for the region of the user, e.g. `California`. - - `Scroll object { scroll_x, scroll_y, type, 3 more }` + - `timezone: optional string` - A scroll action. + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - - `scroll_x: number` + - `type: optional "approximate"` - The horizontal scroll distance. + The type of location approximation. Always `approximate`. - - `scroll_y: number` + - `"approximate"` - The vertical scroll distance. + - `Mcp object { server_label, type, allowed_callers, 9 more }` - - `type: "scroll"` + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](/docs/guides/tools-remote-mcp). - Specifies the event type. For a scroll action, this property is always set to `scroll`. + - `server_label: string` - - `"scroll"` + A label for this MCP server, used to identify it in tool calls. - - `x: number` + - `type: "mcp"` - The x-coordinate where the scroll occurred. + The type of the MCP tool. Always `mcp`. - - `y: number` + - `"mcp"` - The y-coordinate where the scroll occurred. + - `allowed_callers: optional array of "direct" or "programmatic"` - - `keys: optional array of string` + The tool invocation context(s). - The keys being held while scrolling. + - `"direct"` - - `Type object { text, type }` + - `"programmatic"` - An action to type in text. + - `allowed_tools: optional array of string or object { read_only, tool_names }` - - `text: string` + List of allowed tool names or a filter object. - The text to type. + - `McpAllowedTools = array of string` - - `type: "type"` + A string array of allowed tool names - Specifies the event type. For a type action, this property is always set to `type`. + - `McpToolFilter object { read_only, tool_names }` - - `"type"` + A filter object to specify which tools are allowed. - - `Wait object { type }` + - `read_only: optional boolean` - A wait action. + 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: "wait"` + - `tool_names: optional array of string` - Specifies the event type. For a wait action, this property is always set to `wait`. + List of allowed tool names. - - `"wait"` + - `authorization: optional string` - - `actions: optional ComputerActionList` + 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. - Flattened batched actions for `computer_use`. Each action includes an - `type` discriminator and action-specific fields. + - `connector_id: optional "connector_dropbox" or "connector_gmail" or "connector_googlecalendar" or 5 more` - - `Click object { button, type, x, 2 more }` + Identifier for service connectors, like those available in ChatGPT. One of + `server_url`, `connector_id`, or `tunnel_id` must be provided. Learn more + about service connectors [here](/docs/guides/tools-remote-mcp#connectors). - A click action. + Currently supported `connector_id` values are: - - `DoubleClick object { keys, type, x, y }` + - 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` - A double click action. + - `"connector_dropbox"` - - `Drag object { path, type, keys }` + - `"connector_gmail"` - A drag action. + - `"connector_googlecalendar"` - - `Keypress object { keys, type }` + - `"connector_googledrive"` - A collection of keypresses the model would like to perform. + - `"connector_microsoftteams"` - - `Move object { type, x, y, keys }` + - `"connector_outlookcalendar"` - A mouse move action. + - `"connector_outlookemail"` - - `Screenshot object { type }` + - `"connector_sharepoint"` - A screenshot action. + - `defer_loading: optional boolean` - - `Scroll object { scroll_x, scroll_y, type, 3 more }` + Whether this MCP tool is deferred and discovered via tool search. - A scroll action. + - `headers: optional map[string]` - - `Type object { text, type }` + Optional HTTP headers to send to the MCP server. Use for authentication + or other purposes. - An action to type in text. + - `require_approval: optional object { always, never } or "always" or "never"` - - `Wait object { type }` + Specify which of the MCP server's tools require approval. - A wait action. + - `McpToolApprovalFilter object { always, never }` - - `ComputerCallOutput object { id, call_id, output, 4 more }` + Specify which of the MCP server's tools require approval. Can be + `always`, `never`, or a filter object associated with tools + that require approval. - - `id: string` + - `always: optional object { read_only, tool_names }` - The unique ID of the computer call tool output. + A filter object to specify which tools are allowed. - - `call_id: string` + - `read_only: optional boolean` - The ID of the computer tool call that produced the output. + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. - - `output: ResponseComputerToolCallOutputScreenshot` + - `tool_names: optional array of string` - A computer screenshot image used with the computer use tool. + List of allowed tool names. - - `type: "computer_screenshot"` + - `never: optional object { read_only, tool_names }` - Specifies the event type. For a computer screenshot, this property is - always set to `computer_screenshot`. + A filter object to specify which tools are allowed. - - `"computer_screenshot"` + - `read_only: optional boolean` - - `file_id: optional string` + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. - The identifier of an uploaded file that contains the screenshot. + - `tool_names: optional array of string` - - `image_url: optional string` + List of allowed tool names. - The URL of the screenshot image. + - `McpToolApprovalSetting = "always" or "never"` - - `status: "completed" or "incomplete" or "failed" or "in_progress"` + Specify a single approval policy for all tools. One of `always` or + `never`. When set to `always`, all tools will require approval. When + set to `never`, all tools will not require approval. - The status of the message input. One of `in_progress`, `completed`, or - `incomplete`. Populated when input items are returned via API. + - `"always"` - - `"completed"` + - `"never"` - - `"incomplete"` + - `server_description: optional string` - - `"failed"` + Optional description of the MCP server, used to provide more context. - - `"in_progress"` + - `server_url: optional string` - - `type: "computer_call_output"` + The URL for the MCP server. One of `server_url`, `connector_id`, or + `tunnel_id` must be provided. - The type of the computer tool call output. Always `computer_call_output`. + - `tunnel_id: optional string` - - `"computer_call_output"` + The Secure MCP Tunnel ID to use instead of a direct server URL. One of + `server_url`, `connector_id`, or `tunnel_id` must be provided. - - `acknowledged_safety_checks: optional array of object { id, code, message }` + - `CodeInterpreter object { container, type, allowed_callers }` - The safety checks reported by the API that have been acknowledged by the - developer. + A tool that runs Python code to help generate a response to a prompt. - - `id: string` + - `container: string or object { type, file_ids, memory_limit, network_policy }` - The ID of the pending safety check. + The code interpreter container. Can be a container ID or an object that + specifies uploaded file IDs to make available to your code, along with an + optional `memory_limit` setting. - - `code: optional string` + - `string` - The type of the pending safety check. + The container ID. - - `message: optional string` + - `CodeInterpreterToolAuto object { type, file_ids, memory_limit, network_policy }` - Details about the pending safety check. + Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. - - `created_by: optional string` + - `type: "auto"` - The identifier of the actor that created the item. + Always `auto`. - - `Reasoning object { id, summary, type, 3 more }` + - `"auto"` - A description of the chain of thought used by a reasoning model while generating - a response. Be sure to include these items in your `input` to the Responses API - for subsequent turns of a conversation if you are manually - [managing context](/docs/guides/conversation-state). + - `file_ids: optional array of string` - - `id: string` + An optional list of uploaded files to make available to your code. - The unique identifier of the reasoning content. + - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` - - `summary: array of SummaryTextContent` + The memory limit for the code interpreter container. - Reasoning summary content. + - `"1g"` - - `text: string` + - `"4g"` - A summary of the reasoning output from the model so far. + - `"16g"` - - `type: "summary_text"` + - `"64g"` - The type of the object. Always `summary_text`. + - `network_policy: optional ContainerNetworkPolicyDisabled or ContainerNetworkPolicyAllowlist` - - `type: "reasoning"` + Network access policy for the container. - The type of the object. Always `reasoning`. + - `ContainerNetworkPolicyDisabled object { type }` - - `"reasoning"` + - `ContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` - - `content: optional array of object { text, type }` + - `type: "code_interpreter"` - Reasoning text content. + The type of the code interpreter tool. Always `code_interpreter`. - - `text: string` + - `"code_interpreter"` - The reasoning text from the model. + - `allowed_callers: optional array of "direct" or "programmatic"` - - `type: "reasoning_text"` + The tool invocation context(s). - The type of the reasoning text. Always `reasoning_text`. + - `"direct"` - - `"reasoning_text"` + - `"programmatic"` - - `encrypted_content: optional string` + - `ProgrammaticToolCalling object { type }` - The encrypted content of the reasoning item. This is populated by default - for reasoning items returned by `POST /v1/responses` and WebSocket - `response.create` requests. + - `type: "programmatic_tool_calling"` - - `status: optional "in_progress" or "completed" or "incomplete"` + The type of the tool. Always `programmatic_tool_calling`. - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `"programmatic_tool_calling"` - - `"in_progress"` + - `ImageGeneration object { type, action, background, 9 more }` - - `"completed"` + A tool that generates images using the GPT image models. - - `"incomplete"` + - `type: "image_generation"` - - `Compaction object { id, encrypted_content, type, created_by }` + The type of the image generation tool. Always `image_generation`. - A compaction item generated by the [`v1/responses/compact` API](/docs/api-reference/responses/compact). + - `"image_generation"` - - `id: string` + - `action: optional "generate" or "edit" or "auto"` - The unique ID of the compaction item. + Whether to generate a new image or edit an existing image. Default: `auto`. - - `encrypted_content: string` + - `"generate"` - The encrypted content that was produced by compaction. + - `"edit"` - - `type: "compaction"` + - `"auto"` - The type of the item. Always `compaction`. + - `background: optional "transparent" or "opaque" or "auto"` - - `"compaction"` + Background type for the generated image. One of `transparent`, + `opaque`, or `auto`. Default: `auto`. - - `created_by: optional string` + - `"transparent"` - The identifier of the actor that created the item. + - `"opaque"` - - `CodeInterpreterCall object { id, code, container_id, 3 more }` + - `"auto"` - A tool call to run code. + - `input_fidelity: optional "high" or "low"` - - `id: string` + Control how much effort the model will exert to match the style and features, especially facial features, of input images. This parameter is only supported for `gpt-image-1` and `gpt-image-1.5` and later models, unsupported for `gpt-image-1-mini`. Supports `high` and `low`. Defaults to `low`. - The unique ID of the code interpreter tool call. + - `"high"` - - `code: string` + - `"low"` - The code to run, or null if not available. + - `input_image_mask: optional object { file_id, image_url }` - - `container_id: string` + Optional mask for inpainting. Contains `image_url` + (string, optional) and `file_id` (string, optional). - The ID of the container used to run the code. + - `file_id: optional string` - - `outputs: array of object { logs, type } or object { type, url }` + File ID for the mask image. - The outputs generated by the code interpreter, such as logs or images. - Can be null if no outputs are available. + - `image_url: optional string` - - `Logs object { logs, type }` + Base64-encoded mask image. - The logs output from the code interpreter. + - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` - - `logs: string` + The image generation model to use. Default: `gpt-image-1`. - The logs output from the code interpreter. + - `string` - - `type: "logs"` + - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` - The type of the output. Always `logs`. + The image generation model to use. Default: `gpt-image-1`. - - `"logs"` + - `"gpt-image-1"` - - `Image object { type, url }` + - `"gpt-image-1-mini"` - The image output from the code interpreter. + - `"gpt-image-1.5"` - - `type: "image"` + - `moderation: optional "auto" or "low"` - The type of the output. Always `image`. + Moderation level for the generated image. Default: `auto`. - - `"image"` + - `"auto"` - - `url: string` + - `"low"` - The URL of the image output from the code interpreter. + - `output_compression: optional number` - - `status: "in_progress" or "completed" or "incomplete" or 2 more` + Compression level for the output image. Default: 100. - The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. + - `output_format: optional "png" or "webp" or "jpeg"` - - `"in_progress"` + The output format of the generated image. One of `png`, `webp`, or + `jpeg`. Default: `png`. - - `"completed"` + - `"png"` - - `"incomplete"` + - `"webp"` - - `"interpreting"` + - `"jpeg"` - - `"failed"` + - `partial_images: optional number` - - `type: "code_interpreter_call"` + Number of partial images to generate in streaming mode, from 0 (default value) to 3. - The type of the code interpreter tool call. Always `code_interpreter_call`. + - `quality: optional "low" or "medium" or "high" or "auto"` - - `"code_interpreter_call"` + The quality of the generated image. One of `low`, `medium`, `high`, + or `auto`. Default: `auto`. - - `LocalShellCall object { id, action, call_id, 2 more }` + - `"low"` - A tool call to run a command on the local shell. + - `"medium"` - - `id: string` + - `"high"` - The unique ID of the local shell call. + - `"auto"` - - `action: object { command, env, type, 3 more }` + - `size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or "auto"` - Execute a shell command on the server. + 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`. - - `command: array of string` + - `string` - The command to run. + - `"1024x1024" or "1024x1536" or "1536x1024" or "auto"` - - `env: map[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`. - Environment variables to set for the command. + - `"1024x1024"` - - `type: "exec"` + - `"1024x1536"` - The type of the local shell action. Always `exec`. + - `"1536x1024"` - - `"exec"` + - `"auto"` - - `timeout_ms: optional number` + - `LocalShell object { type }` - Optional timeout in milliseconds for the command. + A tool that allows the model to execute shell commands in a local environment. - - `user: optional string` + - `type: "local_shell"` - Optional user to run the command as. + The type of the local shell tool. Always `local_shell`. - - `working_directory: optional string` + - `"local_shell"` - Optional working directory to run the command in. + - `Shell object { type, allowed_callers, environment }` - - `call_id: string` + A tool that allows the model to execute shell commands. - The unique ID of the local shell tool call generated by the model. + - `type: "shell"` - - `status: "in_progress" or "completed" or "incomplete"` + The type of the shell tool. Always `shell`. - The status of the local shell call. + - `"shell"` - - `"in_progress"` + - `allowed_callers: optional array of "direct" or "programmatic"` - - `"completed"` + The tool invocation context(s). - - `"incomplete"` + - `"direct"` - - `type: "local_shell_call"` + - `"programmatic"` - The type of the local shell call. Always `local_shell_call`. + - `environment: optional ContainerAuto or LocalEnvironment or ContainerReference` - - `"local_shell_call"` + - `ContainerAuto object { type, file_ids, memory_limit, 2 more }` - - `LocalShellCallOutput object { id, output, type, status }` + - `LocalEnvironment object { type, skills }` - The output of a local shell tool call. + - `ContainerReference object { container_id, type }` - - `id: string` + - `Custom object { name, type, allowed_callers, 3 more }` - The unique ID of the local shell tool call generated by the model. + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) - - `output: string` + - `name: string` - A JSON string of the output of the local shell tool call. + The name of the custom tool, used to identify it in tool calls. - - `type: "local_shell_call_output"` + - `type: "custom"` - The type of the local shell tool call output. Always `local_shell_call_output`. + The type of the custom tool. Always `custom`. - - `"local_shell_call_output"` + - `"custom"` - - `status: optional "in_progress" or "completed" or "incomplete"` + - `allowed_callers: optional array of "direct" or "programmatic"` - The status of the item. One of `in_progress`, `completed`, or `incomplete`. + The tool invocation context(s). - - `"in_progress"` + - `"direct"` - - `"completed"` + - `"programmatic"` - - `"incomplete"` + - `defer_loading: optional boolean` - - `ShellCall object { id, action, call_id, 5 more }` + Whether this tool should be deferred and discovered via tool search. - A tool call that executes one or more shell commands in a managed environment. + - `description: optional string` - - `id: string` + Optional description of the custom tool, used to provide more context. - The unique ID of the shell tool call. Populated when this item is returned via API. + - `format: optional CustomToolInputFormat` - - `action: object { commands, max_output_length, timeout_ms }` + The input format for the custom tool. Default is unconstrained text. - The shell commands and limits that describe how to run the tool call. + - `Namespace object { description, name, tools, type }` - - `commands: array of string` + Groups function/custom tools under a shared namespace. - - `max_output_length: number` + - `description: string` - Optional maximum number of characters to return from each command. + A description of the namespace shown to the model. - - `timeout_ms: number` + - `name: string` - Optional timeout in milliseconds for the commands. + The namespace name used in tool calls (for example, `crm`). - - `call_id: string` + - `tools: array of object { name, type, allowed_callers, 5 more } or object { name, type, allowed_callers, 3 more }` - The unique ID of the shell tool call generated by the model. + The function/custom tools available inside this namespace. - - `environment: ResponseLocalEnvironment or ResponseContainerReference` + - `Function object { name, type, allowed_callers, 5 more }` - Represents the use of a local environment to perform shell actions. + - `name: string` - - `ResponseLocalEnvironment object { type }` + - `type: "function"` - Represents the use of a local environment to perform shell actions. + - `"function"` - - `type: "local"` + - `allowed_callers: optional array of "direct" or "programmatic"` - The environment type. Always `local`. + The tool invocation context(s). - - `"local"` + - `"direct"` - - `ResponseContainerReference object { container_id, type }` + - `"programmatic"` - Represents a container created with /v1/containers. + - `defer_loading: optional boolean` - - `container_id: string` + Whether this function should be deferred and discovered via tool search. - - `type: "container_reference"` + - `description: optional string` - The environment type. Always `container_reference`. + - `output_schema: optional map[unknown]` - - `"container_reference"` + A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. - - `status: "in_progress" or "completed" or "incomplete"` + - `parameters: optional unknown` - The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. + - `strict: optional boolean` - - `"in_progress"` + Whether to enforce strict parameter validation. If omitted, Responses attempts to use strict validation when the schema is compatible, and falls back to non-strict validation otherwise. - - `"completed"` + - `Custom object { name, type, allowed_callers, 3 more }` - - `"incomplete"` + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) - - `type: "shell_call"` + - `name: string` - The type of the item. Always `shell_call`. + The name of the custom tool, used to identify it in tool calls. - - `"shell_call"` + - `type: "custom"` - - `caller: optional object { type } or object { caller_id, type }` + The type of the custom tool. Always `custom`. - The execution context that produced this tool call. + - `"custom"` - - `Direct object { type }` + - `allowed_callers: optional array of "direct" or "programmatic"` - - `type: "direct"` + The tool invocation context(s). - `"direct"` - - `Program object { caller_id, type }` + - `"programmatic"` - - `caller_id: string` + - `defer_loading: optional boolean` - The call ID of the program item that produced this tool call. + Whether this tool should be deferred and discovered via tool search. - - `type: "program"` + - `description: optional string` - - `"program"` + 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, 5 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` - - `caller: optional object { type } or object { caller_id, type }` + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - The execution context that produced this tool call. + - `region: optional string` - - `Direct object { type }` + Free text input for the region of the user, e.g. `California`. - - `type: "direct"` + - `timezone: optional string` - - `"direct"` + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - - `Program object { caller_id, type }` + - `ApplyPatch object { type, allowed_callers }` - - `caller_id: string` + Allows the assistant to create, delete, or update files using unified diffs. - The call ID of the program item that produced this tool call. + - `type: "apply_patch"` - - `type: "program"` + The type of the tool. Always `apply_patch`. - - `"program"` + - `"apply_patch"` - - `created_by: optional string` + - `allowed_callers: optional array of "direct" or "programmatic"` - The identifier of the actor that created the item. + The tool invocation context(s). - - `ApplyPatchCall object { id, call_id, operation, 4 more }` + - `"direct"` - A tool call that applies file diffs by creating, deleting, or updating files. + - `"programmatic"` - - `id: string` + - `top_p: number` - The unique ID of the apply patch tool call. Populated when this item is returned via API. + An alternative to sampling with temperature, called nucleus sampling, + where the model considers the results of the tokens with top_p probability + mass. So 0.1 means only the tokens comprising the top 10% probability mass + are considered. - - `call_id: string` + We generally recommend altering this or `temperature` but not both. - The unique ID of the apply patch tool call generated by the model. + - `background: optional boolean` - - `operation: object { diff, path, type } or object { path, type } or object { diff, path, type }` + Whether to run the model response in the background. + [Learn more](/docs/guides/background). - One of the create_file, delete_file, or update_file operations applied via apply_patch. + - `completed_at: optional number` - - `CreateFile object { diff, path, type }` + Unix timestamp (in seconds) of when this Response was completed. + Only present when the status is `completed`. - Instruction describing how to create a file via the apply_patch tool. + - `conversation: optional object { id }` - - `diff: string` + The conversation that this response belonged to. Input items and output items from this response were automatically added to this conversation. - Diff to apply. + - `id: string` - - `path: string` + The unique ID of the conversation that this response was associated with. - Path of the file to create. + - `max_output_tokens: optional number` - - `type: "create_file"` + An upper bound for the number of tokens that can be generated for a response, including visible output tokens and [reasoning tokens](/docs/guides/reasoning). - Create a new file with the provided diff. + - `max_tool_calls: optional number` - - `"create_file"` + The maximum number of total calls to built-in tools that can be processed in a response. This maximum number applies across all built-in tool calls, not per individual tool. Any further attempts to call a tool by the model will be ignored. - - `DeleteFile object { path, type }` + - `moderation: optional object { input, output }` - Instruction describing how to delete a file via the apply_patch tool. + Moderation results for the response input and output, if moderated completions were requested. - - `path: string` + - `input: object { categories, category_applied_input_types, category_scores, 3 more } or object { code, message, type }` - Path of the file to delete. + Moderation for the response input. - - `type: "delete_file"` + - `ModerationResult object { categories, category_applied_input_types, category_scores, 3 more }` - Delete the specified file. + A moderation result produced for the response input or output. - - `"delete_file"` + - `categories: map[boolean]` - - `UpdateFile object { diff, path, type }` + A dictionary of moderation categories to booleans, True if the input is flagged under this category. - Instruction describing how to update a file via the apply_patch tool. + - `category_applied_input_types: map[array of "text" or "image"]` - - `diff: string` + Which modalities of input are reflected by the score for each category. - Diff to apply. + - `"text"` - - `path: string` + - `"image"` - Path of the file to update. + - `category_scores: map[number]` - - `type: "update_file"` + A dictionary of moderation categories to scores. - Update an existing file with the provided diff. + - `flagged: boolean` - - `"update_file"` + A boolean indicating whether the content was flagged by any category. - - `status: "in_progress" or "completed"` + - `model: string` - The status of the apply patch tool call. One of `in_progress` or `completed`. + The moderation model that produced this result. - - `"in_progress"` + - `type: "moderation_result"` - - `"completed"` + The object type, which was always `moderation_result` for successful moderation results. - - `type: "apply_patch_call"` + - `"moderation_result"` - The type of the item. Always `apply_patch_call`. + - `Error object { code, message, type }` - - `"apply_patch_call"` + An error produced while attempting moderation for the response input or output. - - `caller: optional object { type } or object { caller_id, type }` + - `code: string` - The execution context that produced this tool call. + The error code. - - `Direct object { type }` + - `message: string` - - `type: "direct"` + The error message. - - `"direct"` + - `type: "error"` - - `Program object { caller_id, type }` + The object type, which was always `error` for moderation failures. - - `caller_id: string` + - `"error"` - The call ID of the program item that produced this tool call. + - `output: object { categories, category_applied_input_types, category_scores, 3 more } or object { code, message, type }` - - `type: "program"` + Moderation for the response output. - - `"program"` + - `ModerationResult object { categories, category_applied_input_types, category_scores, 3 more }` - - `created_by: optional string` + A moderation result produced for the response input or output. - The ID of the entity that created this tool call. + - `categories: map[boolean]` - - `ApplyPatchCallOutput object { id, call_id, status, 4 more }` + A dictionary of moderation categories to booleans, True if the input is flagged under this category. - The output emitted by an apply patch tool call. + - `category_applied_input_types: map[array of "text" or "image"]` - - `id: string` + Which modalities of input are reflected by the score for each category. - The unique ID of the apply patch tool call output. Populated when this item is returned via API. + - `"text"` - - `call_id: string` + - `"image"` - The unique ID of the apply patch tool call generated by the model. + - `category_scores: map[number]` - - `status: "completed" or "failed"` + A dictionary of moderation categories to scores. - The status of the apply patch tool call output. One of `completed` or `failed`. + - `flagged: boolean` - - `"completed"` + A boolean indicating whether the content was flagged by any category. - - `"failed"` + - `model: string` - - `type: "apply_patch_call_output"` + The moderation model that produced this result. - The type of the item. Always `apply_patch_call_output`. + - `type: "moderation_result"` - - `"apply_patch_call_output"` + The object type, which was always `moderation_result` for successful moderation results. - - `caller: optional object { type } or object { caller_id, type }` + - `"moderation_result"` - The execution context that produced this tool call. + - `Error object { code, message, type }` - - `Direct object { type }` + An error produced while attempting moderation for the response input or output. - - `type: "direct"` + - `code: string` - - `"direct"` + The error code. - - `Program object { caller_id, type }` + - `message: string` - - `caller_id: string` + The error message. - The call ID of the program item that produced this tool call. + - `type: "error"` - - `type: "program"` + The object type, which was always `error` for moderation failures. - - `"program"` + - `"error"` - - `created_by: optional string` + - `output_text: optional string` - The ID of the entity that created this tool call output. + SDK-only convenience property that contains the aggregated text output + from all `output_text` items in the `output` array, if any are present. + Supported in the Python and JavaScript SDKs. - - `output: optional string` + - `previous_response_id: optional string` - Optional textual output returned by the apply patch tool. + The unique ID of the previous response to the model. Use this to + create multi-turn conversations. Learn more about + [conversation state](/docs/guides/conversation-state). Cannot be used in conjunction with `conversation`. - - `McpListTools object { id, server_label, tools, 2 more }` + - `prompt: optional ResponsePrompt` - A list of tools available on an MCP server. + Reference to a prompt template and its variables. + [Learn more](/docs/guides/text?api-mode=responses#reusable-prompts). - `id: string` - The unique ID of the list. + The unique identifier of the prompt template to use. - - `server_label: string` + - `variables: optional map[string or ResponseInputText or ResponseInputImage or ResponseInputFile]` - The label of the MCP server. + Optional map of values to substitute in for variables in your + prompt. The substitution values can either be strings, or other + Response input types like images or files. - - `tools: array of object { input_schema, name, annotations, description }` + - `string` - The tools available on the server. + - `ResponseInputText object { text, type, prompt_cache_breakpoint }` - - `input_schema: unknown` + A text input to the model. - The JSON schema describing the tool's input. + - `ResponseInputImage object { detail, type, file_id, 2 more }` - - `name: string` + An image input to the model. Learn about [image inputs](/docs/guides/vision). - The name of the tool. + - `ResponseInputFile object { type, detail, file_data, 4 more }` - - `annotations: optional unknown` + A file input to the model. - Additional annotations about the tool. + - `version: optional string` - - `description: optional string` + Optional version of the prompt template. - The description of the tool. + - `prompt_cache_key: optional string` - - `type: "mcp_list_tools"` + Used by OpenAI to cache responses for similar requests to optimize your cache hit rates. Replaces the `user` field. [Learn more](/docs/guides/prompt-caching). - The type of the item. Always `mcp_list_tools`. + - `prompt_cache_options: optional object { mode, ttl }` - - `"mcp_list_tools"` + The prompt-caching options that were applied to the response. Supported for `gpt-5.6` and later models. - - `error: optional string` + - `mode: "implicit" or "explicit"` - Error message if the server could not list tools. + Whether implicit prompt-cache breakpoints were enabled. - - `McpApprovalRequest object { id, arguments, name, 2 more }` + - `"implicit"` - A request for human approval of a tool invocation. + - `"explicit"` - - `id: string` + - `ttl: "30m"` - The unique ID of the approval request. + The minimum lifetime applied to each cache breakpoint. + + - `"30m"` + + - `prompt_cache_retention: optional "in_memory" or "24h"` + + Deprecated. Use `prompt_cache_options.ttl` instead. + + The retention policy for the prompt cache. Set to `24h` to enable extended prompt caching, which keeps cached prefixes active for longer, up to a maximum of 24 hours. [Learn more](/docs/guides/prompt-caching#prompt-cache-retention). + This field expresses a maximum retention policy, while + `prompt_cache_options.ttl` expresses a minimum cache lifetime. The two + fields are independent and do not interact. + For `gpt-5.5`, `gpt-5.5-pro`, and future models, only `24h` is supported. - - `arguments: string` + For older models that support both `in_memory` and `24h`, the default depends on your organization's data retention policy: - A JSON string of arguments for the tool. + - Organizations without ZDR enabled default to `24h`. + - Organizations with ZDR enabled default to `in_memory` when `prompt_cache_retention` is not specified. - - `name: string` + - `"in_memory"` - The name of the tool to run. + - `"24h"` - - `server_label: string` + - `reasoning: optional Reasoning` - The label of the MCP server making the request. + **gpt-5 and o-series models only** - - `type: "mcp_approval_request"` + Configuration options for + [reasoning models](https://platform.openai.com/docs/guides/reasoning). - The type of the item. Always `mcp_approval_request`. + - `context: optional "auto" or "current_turn" or "all_turns"` - - `"mcp_approval_request"` + Controls which reasoning items are rendered back to the model on later turns. + If omitted or set to `auto`, the model determines the context mode. The + `gpt-5.6` model family defaults to `all_turns`; earlier models default to + `current_turn`. - - `McpApprovalResponse object { id, approval_request_id, approve, 2 more }` + When returned on a response, this is the effective reasoning context mode + used for the response. - A response to an MCP approval request. + - `"auto"` - - `id: string` + - `"current_turn"` - The unique ID of the approval response + - `"all_turns"` - - `approval_request_id: string` + - `effort: optional ReasoningEffort` - The ID of the approval request being answered. + Constrains effort on reasoning for reasoning models. Currently supported + values are `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max`. + Reducing reasoning effort can result in faster responses and fewer tokens + used on reasoning in a response. Not all reasoning models support every + value. See the + [reasoning guide](https://platform.openai.com/docs/guides/reasoning) + for model-specific support. - - `approve: boolean` + - `"none"` - Whether the request was approved. + - `"minimal"` - - `type: "mcp_approval_response"` + - `"low"` - The type of the item. Always `mcp_approval_response`. + - `"medium"` - - `"mcp_approval_response"` + - `"high"` - - `reason: optional string` + - `"xhigh"` - Optional reason for the decision. + - `"max"` - - `McpCall object { id, arguments, name, 6 more }` + - `generate_summary: optional "auto" or "concise" or "detailed"` - An invocation of a tool on an MCP server. + **Deprecated:** use `summary` instead. - - `id: string` + A summary of the reasoning performed by the model. This can be + useful for debugging and understanding the model's reasoning process. + One of `auto`, `concise`, or `detailed`. - The unique ID of the tool call. + - `"auto"` - - `arguments: string` + - `"concise"` - A JSON string of the arguments passed to the tool. + - `"detailed"` - - `name: string` + - `mode: optional string or "standard" or "pro"` - The name of the tool that was run. + Controls the reasoning execution mode for the request. - - `server_label: string` + When returned on a response, this is the effective execution mode. - The label of the MCP server running the tool. + - `string` - - `type: "mcp_call"` + - `"standard" or "pro"` - The type of the item. Always `mcp_call`. + Controls the reasoning execution mode for the request. - - `"mcp_call"` + When returned on a response, this is the effective execution mode. - - `approval_request_id: optional string` + - `"standard"` - 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. + - `"pro"` - - `error: optional string` + - `summary: optional "auto" or "concise" or "detailed"` - The error from the tool call, if any. + A summary of the reasoning performed by the model. This can be + useful for debugging and understanding the model's reasoning process. + One of `auto`, `concise`, or `detailed`. - - `output: optional string` + `concise` is supported for `computer-use-preview` models and all reasoning models after `gpt-5`. - The output from the tool call. + - `"auto"` - - `status: optional "in_progress" or "completed" or "incomplete" or 2 more` + - `"concise"` - The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. + - `"detailed"` - - `"in_progress"` + - `safety_identifier: optional string` - - `"completed"` + A stable identifier used to help detect users of your application that may be violating OpenAI's usage policies. + The IDs should be a string that uniquely identifies each user, with a maximum length of 64 characters. We recommend hashing their username or email address, in order to avoid sending us any identifying information. [Learn more](/docs/guides/safety-best-practices#safety-identifiers). - - `"incomplete"` + - `service_tier: optional "auto" or "default" or "flex" or 2 more` - - `"calling"` + Specifies the processing type used for serving the request. - - `"failed"` + - If set to 'auto', then the request will be processed with the service tier configured in the Project settings. Unless otherwise configured, the Project will use 'default'. + - If set to 'default', then the request will be processed with the standard pricing and performance for the selected model. + - If set to '[flex](/docs/guides/flex-processing)' or '[priority](https://openai.com/api-priority-processing/)', then the request will be processed with the corresponding service tier. + - When not set, the default behavior is 'auto'. - - `CustomToolCall object { call_id, input, name, 4 more }` + When the `service_tier` parameter is set, the response body will include the `service_tier` value based on the processing mode actually used to serve the request. This response value may be different from the value set in the parameter. - A call to a custom tool created by the model. + - `"auto"` - - `call_id: string` + - `"default"` - An identifier used to map this custom tool call to a tool call output. + - `"flex"` - - `input: string` + - `"scale"` - The input for the custom tool call generated by the model. + - `"priority"` - - `name: string` + - `status: optional ResponseStatus` - The name of the custom tool being called. + The status of the response generation. One of `completed`, `failed`, + `in_progress`, `cancelled`, `queued`, or `incomplete`. - - `type: "custom_tool_call"` + - `"completed"` - The type of the custom tool call. Always `custom_tool_call`. + - `"failed"` - - `"custom_tool_call"` + - `"in_progress"` - - `id: optional string` + - `"cancelled"` - The unique ID of the custom tool call in the OpenAI platform. + - `"queued"` - - `caller: optional object { type } or object { caller_id, type }` + - `"incomplete"` - The execution context that produced this tool call. + - `text: optional ResponseTextConfig` - - `Direct object { type }` + Configuration options for a text response from the model. Can be plain + text or structured JSON data. Learn more: - - `type: "direct"` + - [Text inputs and outputs](/docs/guides/text) + - [Structured Outputs](/docs/guides/structured-outputs) - - `"direct"` + - `format: optional ResponseFormatTextConfig` - - `Program object { caller_id, type }` + An object specifying the format that the model must output. - - `caller_id: string` + Configuring `{ "type": "json_schema" }` enables Structured Outputs, + which ensures the model will match your supplied JSON schema. Learn more in the + [Structured Outputs guide](/docs/guides/structured-outputs). - The call ID of the program item that produced this tool call. + The default format is `{ "type": "text" }` with no additional options. - - `type: "program"` + **Not recommended for gpt-4o and newer models:** - - `"program"` + Setting to `{ "type": "json_object" }` enables the older JSON mode, which + ensures the message the model generates is valid JSON. Using `json_schema` + is preferred for models that support it. - - `namespace: optional string` + - `ResponseFormatText object { type }` - The namespace of the custom tool being called. + Default response format. Used to generate text responses. - - `CustomToolCallOutput object { call_id, output, type, 2 more }` + - `type: "text"` - The output of a custom tool call from your code, being sent back to the model. + The type of response format being defined. Always `text`. - - `call_id: string` + - `"text"` - The call ID, used to map this custom tool call output to a custom tool call. + - `ResponseFormatTextJSONSchemaConfig object { name, schema, type, 2 more }` - - `output: string or array of ResponseInputText or ResponseInputImage or ResponseInputFile` + JSON Schema response format. Used to generate structured JSON responses. + Learn more about [Structured Outputs](/docs/guides/structured-outputs). - The output from the custom tool call generated by your code. - Can be a string or an list of output content. + - `name: string` - - `StringOutput = string` + The name of the response format. Must be a-z, A-Z, 0-9, or contain + underscores and dashes, with a maximum length of 64. - A string of the output of the custom tool call. + - `schema: map[unknown]` - - `OutputContentList = array of ResponseInputText or ResponseInputImage or ResponseInputFile` + The schema for the response format, described as a JSON Schema object. + Learn how to build JSON schemas [here](https://json-schema.org/). - Text, image, or file output of the custom tool call. + - `type: "json_schema"` - - `ResponseInputText object { text, type, prompt_cache_breakpoint }` + The type of response format being defined. Always `json_schema`. - A text input to the model. + - `"json_schema"` - - `ResponseInputImage object { detail, type, file_id, 2 more }` + - `description: optional string` - An image input to the model. Learn about [image inputs](/docs/guides/vision). + A description of what the response format is for, used by the model to + determine how to respond in the format. - - `ResponseInputFile object { type, detail, file_data, 4 more }` + - `strict: optional boolean` - A file input to the model. + Whether to enable strict schema adherence when generating the output. + If set to true, the model will always follow the exact schema defined + in the `schema` field. Only a subset of JSON Schema is supported when + `strict` is `true`. To learn more, read the [Structured Outputs + guide](/docs/guides/structured-outputs). - - `type: "custom_tool_call_output"` + - `ResponseFormatJSONObject object { type }` - The type of the custom tool call output. Always `custom_tool_call_output`. + JSON object response format. An older method of generating JSON responses. + Using `json_schema` is recommended for models that support it. Note that the + model will not generate JSON without a system or user message instructing it + to do so. - - `"custom_tool_call_output"` + - `type: "json_object"` - - `id: optional string` + The type of response format being defined. Always `json_object`. - The unique ID of the custom tool call output in the OpenAI platform. + - `"json_object"` - - `caller: optional object { type } or object { caller_id, type }` + - `verbosity: optional "low" or "medium" or "high"` - The execution context that produced this tool call. + Constrains the verbosity of the model's response. Lower values will result in + more concise responses, while higher values will result in more verbose responses. + Currently supported values are `low`, `medium`, and `high`. The default is + `medium`. - - `Direct object { type }` + - `"low"` - - `type: "direct"` + - `"medium"` - The caller type. Always `direct`. + - `"high"` - - `"direct"` + - `top_logprobs: optional number` - - `Program object { caller_id, type }` + An integer between 0 and 20 specifying the maximum number of most likely + tokens to return at each token position, each with an associated log + probability. In some cases, the number of returned tokens may be fewer than + requested. - - `caller_id: string` + - `truncation: optional "auto" or "disabled"` - The call ID of the program item that produced this tool call. + The truncation strategy to use for the model response. - - `type: "program"` + - `auto`: If the input to this Response exceeds + the model's context window size, the model will truncate the + response to fit the context window by dropping items from the beginning of the conversation. + - `disabled` (default): If the input size will exceed the context window + size for a model, the request will fail with a 400 error. - The caller type. Always `program`. + - `"auto"` - - `"program"` + - `"disabled"` - - `usage: ResponseUsage` + - `usage: optional ResponseUsage` - Token accounting for the compaction pass, including cached, reasoning, and total tokens. + Represents token usage details including input tokens, output tokens, + a breakdown of output tokens, and the total tokens used. - `input_tokens: number` @@ -42623,16 +42491,17 @@ Learn when and how to compact long-running conversations in the [conversation st The total number of tokens used. + - `user: optional string` + + This field is being replaced by `safety_identifier` and `prompt_cache_key`. Use `prompt_cache_key` instead to maintain caching optimizations. + A stable identifier for your end-users. + Used to boost cache hit rates by better bucketing similar requests and to help OpenAI detect and prevent abuse. [Learn more](/docs/guides/safety-best-practices#safety-identifiers). + ### Example ```http -curl https://api.openai.com/v1/responses/compact \ - -H 'Content-Type: application/json' \ - -H "Authorization: Bearer $OPENAI_API_KEY" \ - -d '{ - "model": "gpt-5.6-sol", - "previous_response_id": "resp_123" - }' +curl https://api.openai.com/v1/responses/$RESPONSE_ID \ + -H "Authorization: Bearer $OPENAI_API_KEY" ``` #### Response @@ -42641,25 +42510,156 @@ curl https://api.openai.com/v1/responses/compact \ { "id": "id", "created_at": 0, - "object": "response.compaction", + "error": { + "code": "server_error", + "message": "message" + }, + "incomplete_details": { + "reason": "max_output_tokens" + }, + "instructions": "string", + "metadata": { + "foo": "string" + }, + "model": "gpt-5.1", + "object": "response", "output": [ { "id": "id", "content": [ { - "text": "text", - "type": "input_text", - "prompt_cache_breakpoint": { - "mode": "explicit" + "annotations": [ + { + "file_id": "file_id", + "filename": "filename", + "index": 0, + "type": "file_citation" + } + ], + "logprobs": [ + { + "token": "token", + "bytes": [ + 0 + ], + "logprob": 0, + "top_logprobs": [ + { + "token": "token", + "bytes": [ + 0 + ], + "logprob": 0 } + ] } ], - "role": "unknown", + "text": "text", + "type": "output_text" + } + ], + "role": "assistant", "status": "in_progress", "type": "message", "phase": "commentary" } ], + "parallel_tool_calls": true, + "temperature": 1, + "tool_choice": "none", + "tools": [ + { + "name": "name", + "parameters": { + "foo": "bar" + }, + "strict": true, + "type": "function", + "allowed_callers": [ + "direct" + ], + "defer_loading": true, + "description": "description", + "output_schema": { + "foo": "bar" + } + } + ], + "top_p": 1, + "background": true, + "completed_at": 0, + "conversation": { + "id": "id" + }, + "max_output_tokens": 0, + "max_tool_calls": 0, + "moderation": { + "input": { + "categories": { + "foo": true + }, + "category_applied_input_types": { + "foo": [ + "text" + ] + }, + "category_scores": { + "foo": 0 + }, + "flagged": true, + "model": "model", + "type": "moderation_result" + }, + "output": { + "categories": { + "foo": true + }, + "category_applied_input_types": { + "foo": [ + "text" + ] + }, + "category_scores": { + "foo": 0 + }, + "flagged": true, + "model": "model", + "type": "moderation_result" + } + }, + "output_text": "output_text", + "previous_response_id": "previous_response_id", + "prompt": { + "id": "id", + "variables": { + "foo": "string" + }, + "version": "version" + }, + "prompt_cache_key": "prompt-cache-key-1234", + "prompt_cache_options": { + "mode": "implicit", + "ttl": "30m" + }, + "prompt_cache_retention": "in_memory", + "reasoning": { + "context": "auto", + "effort": "none", + "generate_summary": "auto", + "mode": "standard", + "summary": "auto" + }, + "safety_identifier": "safety-identifier-1234", + "service_tier": "auto", + "status": "completed", + "text": { + "format": { + "type": "text" + }, + "verbosity": "low" + }, + "top_logprobs": 0, + "truncation": "auto", "usage": { "input_tokens": 0, "input_tokens_details": { @@ -42671,79 +42671,79 @@ curl https://api.openai.com/v1/responses/compact \ "reasoning_tokens": 0 }, "total_tokens": 0 - } + }, + "user": "user-1234" } ``` ### Example ```http -curl -X POST https://api.openai.com/v1/responses/compact \ +curl https://api.openai.com/v1/responses/resp_123 \ -H "Content-Type: application/json" \ - -H "Authorization: Bearer $OPENAI_API_KEY" \ - -d '{ - "model": "gpt-5.1-codex-max", - "input": [ - { - "role": "user", - "content": "Create a simple landing page for a dog petting café." - }, - { - "id": "msg_001", - "type": "message", - "status": "completed", - "content": [ - { - "type": "output_text", - "annotations": [], - "logprobs": [], - "text": "Below is a single file, ready-to-use landing page for a dog petting café:..." - } - ], - "role": "assistant" - } - ] - }' + -H "Authorization: Bearer $OPENAI_API_KEY" ``` #### Response ```json { - "id": "resp_001", - "object": "response.compaction", - "created_at": 1764967971, + "id": "resp_67cb71b351908190a308f3859487620d06981a8637e6bc44", + "object": "response", + "created_at": 1741386163, + "status": "completed", + "completed_at": 1741386164, + "error": null, + "incomplete_details": null, + "instructions": null, + "max_output_tokens": null, + "model": "gpt-4o-2024-08-06", "output": [ { - "id": "msg_000", "type": "message", + "id": "msg_67cb71b3c2b0819084d481baaaf148f206981a8637e6bc44", "status": "completed", + "role": "assistant", "content": [ { - "type": "input_text", - "text": "Create a simple landing page for a dog petting cafe." + "type": "output_text", + "text": "Silent circuits hum, \nThoughts emerge in data streams— \nDigital dawn breaks.", + "annotations": [] + } + ] } ], - "role": "user" + "parallel_tool_calls": true, + "previous_response_id": null, + "reasoning": { + "effort": null, + "summary": null }, - { - "id": "cmp_001", - "type": "compaction", - "encrypted_content": "gAAAAABpM0Yj-...=" + "store": true, + "temperature": 1.0, + "text": { + "format": { + "type": "text" } - ], + }, + "tool_choice": "auto", + "tools": [], + "top_p": 1.0, + "truncation": "disabled", "usage": { - "input_tokens": 139, + "input_tokens": 32, "input_tokens_details": { "cached_tokens": 0, "cache_write_tokens": 0 }, - "output_tokens": 438, + "output_tokens": 18, "output_tokens_details": { - "reasoning_tokens": 64 + "reasoning_tokens": 0 }, - "total_tokens": 577 - } + "total_tokens": 50 + }, + "user": null, + "metadata": {} } ```